home *** CD-ROM | disk | FTP | other *** search
/ Risc World 3 / Risc World 3.iso / SOFTWARE / ISSUE2 / CDWRITING / FRONTEND / Docs / AMPlayer_h < prev    next >
Text File  |  2001-12-31  |  140KB  |  1,646 lines
  1. <html><!--
  2.   Auto-generated using XSLT stylesheet created by Justin Fletcher.
  3.   
  4.   Visual artifacts may occur on some browsers where the use of
  5.   list items, immediately followed by paragraph elements are not
  6.   condensed to a plain line. This is a browser fault, rather than
  7.   a structural fault. Contact the supplier of your browser for 
  8.   more details.
  9. -->
  10. <head><meta content="text/html; charset=UTF-8" http-equiv="Content-Type"><title>RISC OS Programmers Reference Manuals : AMPlayer</title></head><body bgcolor="white" text="black" link="blue" alink="red" vlink="darkblue"><hr><h1>AMPlayer</h1><hr><dl><dt><h2>Contents</h2></dt><dd><ul><li><a href="#section_introduction_and_overview">Introduction and Overview</a></li><li><a href="#section_terminology">Terminology</a></li><li><a href="#section_technical_details">Technical Details</a><ul><li><a href="#subsection_mpeg_data_input_methods">MPEG data input methods</a><ul><li><a href="#category_file_playback">File playback</a></li><li><a href="#category_streaming_playback">Streaming playback</a></li></ul></li><li><a href="#subsection_file_output_methods">File output methods</a><ul><li><a href="#category_8_bit_sound_output">8 bit sound output</a></li><li><a href="#category_16_bit_sound_output">16 bit sound output</a></li><li><a href="#category_sharedsound_output">SharedSound output</a></li><li><a href="#category_streaming_output">Streaming output</a></li></ul></li><li><a href="#subsection_multiple_instantiation">Multiple instantiation</a><ul><li><a href="#subsubsection_user_front_ends">User front ends</a></li><li><a href="#subsubsection_plugins">Plugins</a></li><li><a href="#subsubsection__commands">* Commands</a></li></ul></li><li><a href="#subsection_data_structures">Data structures</a><ul><li><a href="#subsubsection_file_information_block">File Information Block</a><ul><li><a href="#category_projected_total_time">Projected total time</a></li><li><a href="#category_id3v1_genre_values">ID3v1 genre values</a></li><li><a href="#category_id3v1.1_track_numbers">ID3v1.1 track numbers</a></li><li><a href="#category_vuvar_values">VU-var values</a></li><li><a href="#category_bitrate_values">Bitrate values</a></li></ul></li><li><a href="#subsubsection_frame_information_block">Frame Information Block</a></li><li><a href="#subsubsection_plugin_information_block">Plugin Information Block</a></li><li><a href="#subsubsection_idtag_information_block">IDTag Information block</a></li><li><a href="#subsubsection_idframe_information_block">IDFrame Information block</a></li></ul></li></ul></li><li><a href="#section_system_variables">System variables</a><ul><li><a href="#sysvar_amplayer_buffer_">AMPlayer$Buffer$*</a></li><li><a href="#sysvar_amplayer_filebuffer">AMPlayer$FileBuffer</a></li><li><a href="#sysvar_amplayer_volume">AMPlayer$Volume</a></li><li><a href="#sysvar_amplayer_decimationthreshold">AMPlayer$DecimationThreshold</a></li></ul></li><li><a href="#section_service_calls">Service calls</a><ul><li><a href="#service_amplayer">AMPlayer</a></li><li><a href="#service_amplayer-0">AMPlayer 0 - Initialising</a></li><li><a href="#service_amplayer-1">AMPlayer 1 - Dying</a></li><li><a href="#service_amplayer-2">AMPlayer 2 - Start</a></li><li><a href="#service_amplayer-3">AMPlayer 3 - Stop</a></li><li><a href="#service_amplayer-4">AMPlayer 4 - Change</a></li><li><a href="#service_amplayer-5">AMPlayer 5 - ID3v2</a></li><li><a href="#service_amplayer-6">AMPlayer 6 - StreamBuffersAvailable</a></li></ul></li><li><a href="#section_swi_calls">SWI calls</a><ul><li><a href="#swi_amplayer_play">AMPlayer_Play</a></li><li><a href="#swi_amplayer_stop">AMPlayer_Stop</a></li><li><a href="#swi_amplayer_pause">AMPlayer_Pause</a></li><li><a href="#swi_amplayer_locate">AMPlayer_Locate</a></li><li><a href="#swi_amplayer_info">AMPlayer_Info</a></li><li><a href="#swi_amplayer_control">AMPlayer_Control</a></li><li><a href="#swi_amplayer_control-0">AMPlayer_Control 0 - Volume</a></li><li><a href="#swi_amplayer_control-1">AMPlayer_Control 1 - BufferSize</a></li><li><a href="#swi_amplayer_control-2">AMPlayer_Control 2 - StackSize</a></li><li><a href="#swi_amplayer_control-3">AMPlayer_Control 3 - ID3v2Control</a></li><li><a href="#swi_amplayer_control-3-_0">AMPlayer_Control 3, 0 - ID3v2State</a></li><li><a href="#swi_amplayer_control-3-_1">AMPlayer_Control 3, 1 - ID3v2Filtering</a></li><li><a href="#swi_amplayer_control-4">AMPlayer_Control 4 - Transience</a></li><li><a href="#swi_amplayer_control-5">AMPlayer_Control 5 - DecimationControl</a></li><li><a href="#swi_amplayer_plugin">AMPlayer_Plugin</a></li><li><a href="#swi_amplayer_fileinfo">AMPlayer_FileInfo</a></li><li><a href="#swi_amplayer_streamopen">AMPlayer_StreamOpen</a></li><li><a href="#swi_amplayer_streamclose">AMPlayer_StreamClose</a></li><li><a href="#swi_amplayer_streamgivedata">AMPlayer_StreamGiveData</a></li><li><a href="#swi_amplayer_streaminfo">AMPlayer_StreamInfo</a></li><li><a href="#swi_amplayer_metadatapollchange">AMPlayer_MetaDataPollChange</a></li><li><a href="#swi_amplayer_metadatalookup">AMPlayer_MetaDataLookup</a></li><li><a href="#swi_amplayer_soundsystem">AMPlayer_SoundSystem</a></li><li><a href="#swi_amplayer_streamreaddata">AMPlayer_StreamReadData</a></li><li><a href="#swi_amplayer_instance">AMPlayer_Instance</a></li><li><a href="#swi_amplayer_instance-0">AMPlayer_Instance 0 - Current</a></li><li><a href="#swi_amplayer_instance-1">AMPlayer_Instance 1 - Create</a></li><li><a href="#swi_amplayer_instance-2">AMPlayer_Instance 2 - Destroy</a></li><li><a href="#swi_amplayer_instance-3">AMPlayer_Instance 3 - ReadBase</a></li><li><a href="#swi_amplayer_instance-4">AMPlayer_Instance 4 - Enumerate</a></li></ul></li><li><a href="#section_entry_points">Entry points</a><ul><li><a href="#entry_plugin_preprocess">Plugin_PreProcess</a></li><li><a href="#entry_plugin_postprocess">Plugin_PostProcess</a></li></ul></li><li><a href="#section_commands">*Commands</a><ul><li><a href="#command_aminfo">AMInfo</a></li><li><a href="#command_amlocate">AMLocate</a></li><li><a href="#command_ampause">AMPause</a></li><li><a href="#command_amplay">AMPlay</a></li><li><a href="#command_amstop">AMStop</a></li><li><a href="#command_amvolume">AMVolume</a></li></ul></li></ul></dd></dl><hr><dl><dt><h2><a name="section_introduction_and_overview">Introduction and Overview</a></h2></dt><dd><dl><dd><p>AMPlayer is a module for playing Audio MPEG data through the computers
  11. sound output, or to a streaming destination. Where sound is to be output, it
  12. will select the 8 or 16 bit output depending on the normal configuration
  13. (and availability).</p></dd></dl></dd><dd><dl><dd><p>The module has been designed so it is easy to make other frontends, or
  14. add support for the module to existing player-frontends.</p></dd></dl></dd><dd><dl><dd><p>The AMPlayer module supports MPEG version 1, 2 and 2.5, for layers I, II
  15. and III. Mixed data may be safely used with the module. The AMPlayer is
  16. resilient when faced with corrupt data, and will skip unknown data in a safe
  17. manner. Streams of data may contain ID3v2 tags, and may be terminated by
  18. ID3v1.1 tags. ID3v2 footers are skipped and not parsed.</p></dd></dl></dd></dl><hr><dl><dt><h2><a name="section_terminology">Terminology</a></h2></dt><dd><dl><dd><p>MPEG audio data is used as a generic term, covering MPEG 1/2/2.5 audio
  19. data, using layers I, II, or III.</p></dd></dl></dd><dd><dl><dd><p>The term VBR is used to mean 'Variable Bit-Rate'. VBR data is data which
  20. contains non-constant bitrate through the track. It is still assumed that
  21. the MPEG version and layer remain constant.</p></dd></dl></dd></dl><hr><dl><dt><h2><a name="section_technical_details">Technical Details</a></h2></dt><dd><dl><dd><p>In order to play MPEG audio data, AMPlayer processes data in the
  22. background using callbacks. This allows the module to continue in, and out
  23. of the desktop with no supervision from any other component.</p></dd></dl></dd><dt><h4><a name="subsection_mpeg_data_input_methods">MPEG data input methods</a></h4></dt><dd><dl><dd><p>MPEG audio data can come from either a file, or from a data stream. When
  24. operating in both of these modes, the functionality of AMPlayer is similar.
  25. </p></dd><dd><h5><b><a name="category_file_playback">File playback</a></b></h5>
  26. <p>During file playback, the AMPlayer module continually takes data from
  27. the file as it needs it. File data is buffered by the module.</p>
  28.  
  29. <p>File playback will initially read the ID3v1.1 tags from the file if
  30. present, and store these for later retrieval by front ends. During playback,
  31. ID3v2 tags will be processed (if enabled) and services issued announcing
  32. their arrival.</p>
  33. </dd><dd><h5><b><a name="category_streaming_playback">Streaming playback</a></b></h5>
  34. <p>When streaming, an application must feed data to AMPlayer in a timely
  35. fashion. Data is supplied to a ring of buffers which are drained
  36. individually by the AMPlayer module. As each buffer is emptied it is the job
  37. of the streaming application to provide further data or to close the stream.
  38. </p>
  39.  
  40. <p>The player will take data from buffers supplied by the streaming
  41. application in the order given. When the end of a buffer is reached, the
  42. player will continue seamlessly to the next buffer. There is no necessity to
  43. provide frame-aligned data to the buffers. Where frames straddle the buffer
  44. end, it may be necessary for the player to retain the buffer until the frame
  45. can be processed. Because of this streaming application must supply at least
  46. two buffers and at least 2000  bytes in total for
  47. streaming playback. When a buffer is no longer required, a service will be
  48. issued to inform the streaming application.</p>
  49.  
  50. <p>Metadata can be supplied to the AMPlayer module during streaming. This
  51. data will be inserted in-line with the stream and made available at the
  52. point at which it is played. This data is incompatible with ID3v1.1 data,
  53. and with ID3v2 data. During playback, ID3v1.1 and ID3v2 tags are skipped.
  54. ID3v2 tags larger than the total size of the ring of buffers will cause
  55. the player to stall.</p>
  56. </dd></dl></dd><dt><h4><a name="subsection_file_output_methods">File output methods</a></h4></dt><dd><dl><dd><p>AMPlayer is able to output to a number of different destinations. Where
  57. the destination is the physical sound system (8bit, 16bit or SharedSound),
  58. the interface to the module is unchanged.</p></dd><dd><h5><b><a name="category_8_bit_sound_output">8 bit sound output</a></b></h5>
  59. <p>All sound output is generated as 16bit-stereo data. When only the 8bit
  60. sound system is available, a lookup table will be used by the output code
  61. to generate the correct logarithmic output. This will result in a slight
  62. degradation in quality, but only to the level of the system accuracy. The
  63. overall frequency of the sound system will track that of the sound being
  64. generated to the limits of the sound system itself. This may result in
  65. further inaccuracies.</p>
  66.  
  67. <p>Because AMPlayer takes over the entire sound system to
  68. handle its output, no other sounds (for example, the system beep) will be
  69. heard in this mode. </p>
  70.  
  71. </dd><dd><h5><b><a name="category_16_bit_sound_output">16 bit sound output</a></b></h5>
  72. <p>Where 16 bit sound is available, but SharedSound support is not, the
  73. standard 16 bit sound drivers will be used. The overall frequency of the
  74. sound system will track the sound being output to the limits that it is
  75. capable.</p>
  76.  
  77. <p>In this mode, AMPlayer uses the entire 16 bit sound system. As a
  78. consequence, no other sound will be generated whilst AMPlayer is playing.
  79. </p>
  80.  
  81. </dd><dd><h5><b><a name="category_sharedsound_output">SharedSound output</a></b></h5>
  82. <p>Where the SharedSound module is available, it will be used by the
  83. AMPlayer module. When playing through the SharedSound module, the frequency
  84. of the sound system is unaffected by playback. In this mode, the sound most
  85. closely matches that which would be generated within the limits of the sound
  86. system and its configuration. Importantly, if the overall sound system
  87. frequency is configured lower than any of the clients of SharedSound, the
  88. output quality will suffer.</p>
  89.  
  90. <p>Sound from other sources is unaffected by AMPlayer playback, allowing
  91. other clients to share the sound system.</p>
  92.  
  93. </dd><dd><h5><b><a name="category_streaming_output">Streaming output</a></b></h5>
  94. <p>AMPlayer can be used to stream generated sound data to any other
  95. destination through the use of the streaming output interface. In this mode,
  96. the sound system is totally unaffected by processing performed by the
  97. module. The streaming interface can obtain the frequency at which the data
  98. being read should be played through this interface.
  99. </p>
  100.  
  101. </dd></dl></dd><dt><h4><a name="subsection_multiple_instantiation">Multiple instantiation</a></h4></dt><dd><dl><dd><p>AMPlayer is able to function as a decoder for multiple clients. It
  102. achieves this by multiple instantiation of the AMPlayer module. The
  103. SWI <a href="#swi_amplayer_instance">AMPlayer_Instance</a>
  104. manages the instances for clients such that it is not necessary for
  105. every client to duplicate the same code.</p></dd><dd><p>In addition to this, all AMPlayer SWIs may have bit 31 of their flags
  106. set to indicate that the operation should be directed to the instance of
  107. the AMPlayer module held in R8. This allows background processes to
  108. communicate with just the instance to which they are interested. When
  109. services are issued to notify clients of events from the decoder, R8 will
  110. be set to the instance handle that generated the service.</p></dd><dd><p>If a SWI is not directed at a particular instance, then the currently
  111. preferred instance will deal with the request.</p></dd><dt><h4><a name="subsubsection_user_front_ends">User front ends</a></h4></dt><dd>
  112. <p>Front end applications which are controlled by the user, queue
  113. tracks, or just monitor the state of the player should only communicate
  114. with the base instance of AMPlayer. This allows them to function with
  115. any number of other concurrent utilities.</p>
  116.  
  117. <p>Under most circumstances it is advisable that front ends not worry
  118. about the existance of multiple instances and merely communicate with the
  119. currently preferred instance. This allows for the greatest flexibility
  120. with clients selecting alternative instances as the private for control
  121. if necessary</p>
  122. </dd><dt><h4><a name="subsubsection_plugins">Plugins</a></h4></dt><dd>
  123. <p>Plugins should be aware of the existance of plugins, and only register
  124. themselves with the base instance unless explicitly requested otherwise.
  125. Because of their nature, plugins are only really suitable for the base
  126. instance, or a secondary instance which is being mixed with the base.</p>
  127. </dd><dt><h4><a name="subsubsection__commands">* Commands</a></h4></dt><dd>
  128. <p>*Commands will always be issued to the currently 'preferred' instance.
  129. In general this will be the base, but under specialised circumstances
  130. another instance may be preferred. The AMPlayer module itself will retain
  131. the current preferred instance through all operations, and therefore the
  132. only mechanism by which another AMPlayer instance may be the preferred is by
  133. explicitly issuing the relevant OS_Module, or by issuing a * Command
  134. directly to an instance.</p>
  135. </dd></dl></dd><dt><h4><a name="subsection_data_structures">Data structures</a></h4></dt><dd><dl><dd><p>In order to communicate with AMPlayer, a number of data structures are
  136. required. These provide information about the streams being processed.</p></dd><dt><h4><a name="subsubsection_file_information_block">File Information Block</a></h4></dt><dd>
  137. <p>The File Information Block provides information about the file currently
  138. being played.
  139.  
  140. <table summary="Opaque table of offset/contents" border="0"><tr><th align="right" valign="bottom">Offset</th><th align="left" valign="bottom">Required flags</th><th align="left" valign="bottom">Contents</th></tr>
  141. <tr><td valign="top" align="right">+0</td><td valign="top" align="left">none</td><td valign="top" align="left">flags :
  142.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  143.    <tr><td valign="top" align="right">0</td><td valign="top" align="left" colspan="2">Total time valid</td></tr>
  144.    <tr><td valign="top" align="right">1</td><td valign="top" align="left" colspan="2">Elapsed time valid</td></tr>
  145.    <tr><td valign="top" align="right">2</td><td valign="top" align="left" colspan="2">ID3 tag info pointers valid</td></tr>
  146.    <tr><td valign="top" align="right">3</td><td valign="top" align="left" colspan="2">VU values valid</td></tr>
  147.    <tr><td valign="top" align="right">4</td><td valign="top" align="left" colspan="2">Error message pointer valid</td></tr>
  148.    <tr><td valign="top" align="right">5</td><td valign="top" align="left" colspan="2">Next filename pointer valid</td></tr>
  149.    <tr><td valign="top" align="right">6</td><td valign="top" align="left" colspan="2">File uses variable bit rate, high and low rates valid</td></tr>
  150.    <tr><td valign="top" align="right">7</td><td valign="top" align="left" colspan="2">ID3v1.1 track valid</td></tr>
  151.    <tr><td valign="top" align="right">8</td><td valign="top" align="left" colspan="2">Data comes from stream</td></tr>
  152.    <tr><td valign="top" align="right">9-31</td><td valign="top" align="left" colspan="2">Reserved, must be zero</td></tr>
  153.   </table>
  154. </td></tr>
  155. <tr><td valign="top" align="right">+4</td><td valign="top" align="left">none</td><td valign="top" align="left">buffer usage ratio in % (*)</td></tr>
  156. <tr><td valign="top" align="right">+8</td><td valign="top" align="left">bit 0</td><td valign="top" align="left">projected total time in cs</td></tr>
  157. <tr><td valign="top" align="right">+12</td><td valign="top" align="left">bit 1</td><td valign="top" align="left">time elapsed in cs</td></tr>
  158. <tr><td valign="top" align="right">+16</td><td valign="top" align="left">bit 2</td><td valign="top" align="left">pointer to ID3 song title</td></tr>
  159. <tr><td valign="top" align="right">+20</td><td valign="top" align="left">bit 2</td><td valign="top" align="left">pointer to ID3 artist</td></tr>
  160. <tr><td valign="top" align="right">+24</td><td valign="top" align="left">bit 2</td><td valign="top" align="left">pointer to ID3 album name</td></tr>
  161. <tr><td valign="top" align="right">+28</td><td valign="top" align="left">bit 2</td><td valign="top" align="left">pointer to ID3 year string</td></tr>
  162. <tr><td valign="top" align="right">+32</td><td valign="top" align="left">bit 2</td><td valign="top" align="left">pointer to ID3 comment</td></tr>
  163. <tr><td valign="top" align="right">+36</td><td valign="top" align="left">bit 3</td><td valign="top" align="left">left channel VU</td></tr>
  164. <tr><td valign="top" align="right">+40</td><td valign="top" align="left">bit 3</td><td valign="top" align="left">right channel VU</td></tr>
  165. <tr><td valign="top" align="right">+44</td><td valign="top" align="left">none</td><td valign="top" align="left">main volume (0..127) (*)</td></tr>
  166. <tr><td valign="top" align="right">+48</td><td valign="top" align="left">bit 4</td><td valign="top" align="left">pointer to most recent error/warning message, or 0 if no message is pending</td></tr>
  167. <tr><td valign="top" align="right">+52</td><td valign="top" align="left">bit 5</td><td valign="top" align="left">pointer to filename of the "next" file, or 0 if no file currently queued</td></tr>
  168. <tr><td valign="top" align="right">+56</td><td valign="top" align="left">bit 2</td><td valign="top" align="left">ID3v1 genre (a number)</td></tr>
  169. <tr><td valign="top" align="right">+60</td><td valign="top" align="left">bit 2+7</td><td valign="top" align="left">ID3v1.1 track (a number), or 0 if not specified</td></tr>
  170. <tr><td valign="top" align="right">+64</td><td valign="top" align="left">bit 6</td><td valign="top" align="left">lowest bitrate used</td></tr>
  171. <tr><td valign="top" align="right">+68</td><td valign="top" align="left">bit 6</td><td valign="top" align="left">highest bitrate used</td></tr>
  172. </table>
  173. </p>
  174.  
  175. <p>Fields marked with (*) are not valid when returned from an
  176. AMPlayer_FileInfo call.</p>
  177.  
  178. <h5><b><a name="category_projected_total_time">Projected total time</a></b></h5>
  179. <p>The projected total time for the track is based on the bitrate used by
  180. the file so far (unless supplied in another manner). It is assumed that the
  181. bitrate remains constant for this calculation. The total time given will be
  182. wrong if :
  183. <ul><li>the file size is unknown, e.g. if playing a stream</li><li>the frame type will later change in a way that alters the number of bytes
  184.    per frame (eg change in bit rate)</li><li>the data is partially corrupt or contains skippable data (ID3v2 tags,
  185.    rogue unsynchronised data, etc)</li></ul>
  186. </p>
  187.  
  188. <p>None of the above exceptions are true in the vast majority of MPEG files.
  189. The first case is determined by the module, and bit 0 of the flags will be
  190. clear. The second case cannot be known in advance, and it will also affect
  191. the elapsed time. No matter what happens, the time will always move forward,
  192. it just might not be counting centiseconds in these cases.</p>
  193.  
  194. <p>Within VBR files generated by the Xing encoder (or applying a Xing
  195. compatible header) the total time will be calculated from the header. If the
  196. file has been truncated, this time will be estimated based on the
  197. information in the header.</p>
  198.  
  199.  
  200. <h5><b><a name="category_id3v1_genre_values">ID3v1 genre values</a></b></h5>
  201. <p>
  202. ID3v1 genre values are defined elsewhere. See http://www.id3.org for more
  203. details.
  204. </p>
  205.  
  206.  
  207. <h5><b><a name="category_id3v1.1_track_numbers">ID3v1.1 track numbers</a></b></h5>
  208. <p>
  209. ID3v1.1 is an extension to ID3 which, if present, declares the track number
  210. within an album.
  211. </p>
  212.  
  213.  
  214. <h5><b><a name="category_vuvar_values">VU-var values</a></b></h5>
  215. <p>
  216. When the VU level is available, it is a number between 0 and 255. The value
  217. is from -42 to 0 dB, in 1/6th dB steps. The level is the peak of the average
  218. level since last calling this SWI.
  219. </p>
  220.  
  221.  
  222. <h5><b><a name="category_bitrate_values">Bitrate values</a></b></h5>
  223. <p>Where VBR Audio MPEG data is being processed, the high and low bitrate
  224. values are used to indicate the current known limits of the data.
  225. </p>
  226.  
  227.  
  228. </dd><dt><h4><a name="subsubsection_frame_information_block">Frame Information Block</a></h4></dt><dd>
  229. <p>The Frame Information Block provides information about the most recent
  230. frame processed.
  231. <table summary="Opaque table of offset/contents" border="0"><tr><th align="right" valign="bottom">Offset</th><th align="left" valign="bottom">Contents</th></tr>
  232.  
  233. <tr><td valign="top" align="right">+0</td><td valign="top" align="left">MPEG version as 3 ASCII chars and a 0 terminator, e.g. "2.0"</td></tr>
  234. <tr><td valign="top" align="right">+4</td><td valign="top" align="left">layer type (1..3). 0 is unknown layer</td></tr>
  235. <tr><td valign="top" align="right">+8</td><td valign="top" align="left">sampling frequency in Hz</td></tr>
  236. <tr><td valign="top" align="right">+12</td><td valign="top" align="left">bitrate in kbit/sec</td></tr>
  237. <tr><td valign="top" align="right">+16</td><td valign="top" align="left">mode :
  238.  <table summary="Opaque table of values" border="0"><tr><th align="right" valign="bottom">Mode</th><th align="left" valign="bottom">Meaning</th></tr>
  239.   <tr><td valign="top" align="right">0</td><td valign="top" align="left">Stereo</td></tr>
  240.   <tr><td valign="top" align="right">1</td><td valign="top" align="left">Joint-stereo</td></tr>
  241.   <tr><td valign="top" align="right">2</td><td valign="top" align="left">Dual channel</td></tr>
  242.   <tr><td valign="top" align="right">3</td><td valign="top" align="left">Single channel</td></tr>
  243.  </table>
  244. </td></tr>
  245. <tr><td valign="top" align="right">+20</td><td valign="top" align="left">number of channels</td></tr>
  246. <tr><td valign="top" align="right">+24</td><td valign="top" align="left">frame flags :
  247.  <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  248.   <tr><td valign="top" align="right">0</td><td valign="top" align="left" colspan="2">Copyright</td></tr>
  249.   <tr><td valign="top" align="right">1</td><td valign="top" align="left" colspan="2">Original</td></tr>
  250.   <tr><td valign="top" align="right">2</td><td valign="top" align="left" colspan="2">CRC</td></tr>
  251.  </table>
  252. </td></tr>
  253. <tr><td valign="top" align="right">+28</td><td valign="top" align="left">pointer to left channel DCT array (*)</td></tr>
  254. <tr><td valign="top" align="right">+32</td><td valign="top" align="left">pointer to right channel DCT array (*)</td></tr>
  255.  
  256. </table>
  257. </p>
  258.  
  259. <p>Fields marked with (*) are not valid when returned from an
  260. AMPlayer_FileInfo call.</p>
  261. </dd><dt><h4><a name="subsubsection_plugin_information_block">Plugin Information Block</a></h4></dt><dd>
  262. <p>The Plugin Information Block is used when registering and enumerating
  263. plugins present.
  264. <table summary="Opaque table of offset/contents" border="0"><tr><th align="right" valign="bottom">Offset</th><th align="left" valign="bottom">Contents</th></tr>
  265.  <tr><td valign="top" align="right">+0</td><td valign="top" align="left">Filter name, padded with 0's (16 chars)</td></tr>
  266.  <tr><td valign="top" align="right">+16</td><td valign="top" align="left">Filter author, padded with 0's (32 chars)</td></tr>
  267.  <tr><td valign="top" align="right">+48</td><td valign="top" align="left">Filter version, padded with 0's (8 chars)</td></tr>
  268. </table>
  269. </p>
  270.  
  271. </dd><dt><h4><a name="subsubsection_idtag_information_block">IDTag Information block</a></h4></dt><dd>
  272. <p>The IDTag Information Block is passed to the service handlers for ID3v2
  273. processing. It provides information on the overall structure of the ID3v2
  274. tag.
  275.  
  276. <table summary="Opaque table of offset/contents" border="0"><tr><th align="right" valign="bottom">Offset</th><th align="left" valign="bottom">Contents</th></tr>
  277. <tr><td valign="top" align="right">+0</td><td valign="top" align="left">Version of original tag data (major * 256 + minor)</td></tr>
  278. <tr><td valign="top" align="right">+4</td><td valign="top" align="left">Header flags :
  279. <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Name</th><th align="left" valign="bottom">Meaning</th></tr>
  280.  <tr><td valign="top" align="right">7</td><td valign="top">HEADERF_UNSYNCHRONISED</td><td valign="top" align="left" colspan="2">Data was unsynchronised</td></tr>
  281.  <tr><td valign="top" align="right">6</td><td valign="top">HEADERF_EXTENDEDHEADER</td><td valign="top" align="left" colspan="2">Extended header was present (ignored at present)</td></tr>
  282.  <tr><td valign="top" align="right">5</td><td valign="top">HEADERF_EXPERIMENTAL</td><td valign="top" align="left" colspan="2">Tag is experimental (should never be seen by decoder)</td></tr>
  283.  <tr><td valign="top" align="right">4</td><td valign="top">HEADERF_FOOTER</td><td valign="top" align="left" colspan="2">Footer was included (has been ignored)</td></tr>
  284.  <tr><td valign="top" align="right">other</td><td valign="top"></td><td valign="top" align="left" colspan="2">reserved, must be 0</td></tr>
  285. </table>
  286. </td></tr>
  287.  
  288. </table>
  289. </p>
  290.  
  291. </dd><dt><h4><a name="subsubsection_idframe_information_block">IDFrame Information block</a></h4></dt><dd>
  292. <p>The IDFrame Information Block is passed to the service handlers for ID3v2
  293. processing. It provides information on the specific ID3v2 frame being
  294. processed.
  295.  
  296. <table summary="Opaque table of offset/contents" border="0"><tr><th align="right" valign="bottom">Offset</th><th align="left" valign="bottom">Contents</th></tr>
  297.  <tr><td valign="top" align="right">+0</td><td valign="top" align="left">frame number (within this tag)</td></tr>
  298.  <tr><td valign="top" align="right">+4</td><td valign="top" align="left">frame name (0 terminated)</td></tr>
  299.  <tr><td valign="top" align="right">+12</td><td valign="top" align="left">flags for this frame :
  300.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Name</th><th align="left" valign="bottom">Meaning</th></tr>
  301.    <tr><td valign="top" align="right">0</td><td valign="top">FRAMEF_HASLENGTH</td><td valign="top" align="left" colspan="2">Length field was given</td></tr>
  302.    <tr><td valign="top" align="right">1</td><td valign="top">FRAMEF_UNSYNCHRONISED</td><td valign="top" align="left" colspan="2">Frame was unsynchronised</td></tr>
  303.    <tr><td valign="top" align="right">2</td><td valign="top">FRAMEF_ENCRYPTED</td><td valign="top" align="left" colspan="2">Frame was encrypted (N/I)</td></tr>
  304.    <tr><td valign="top" align="right">3</td><td valign="top">FRAMEF_COMPRESSED</td><td valign="top" align="left" colspan="2">Frame was compressed</td></tr>
  305.    <tr><td valign="top" align="right">6</td><td valign="top">FRAMEF_GROUP</td><td valign="top" align="left" colspan="2">Frame is one of a group</td></tr>
  306.    <tr><td valign="top" align="right">12</td><td valign="top">FRAMEF_READONLY</td><td valign="top" align="left" colspan="2">Frame should not be edited</td></tr>
  307.    <tr><td valign="top" align="right">13</td><td valign="top">FRAMEF_FILEDISCARD</td><td valign="top" align="left" colspan="2">Discard frame if file changed</td></tr>
  308.    <tr><td valign="top" align="right">14</td><td valign="top">FRAMEF_TAGDISCARD</td><td valign="top" align="left" colspan="2">Discard frame if tag changed</td></tr>
  309.    <tr><td valign="top" align="right">other</td><td valign="top"></td><td valign="top" align="left" colspan="2">reserved, must be 0</td></tr>
  310.   </table>
  311.  </td></tr>
  312.  <tr><td valign="top" align="right">+16</td><td valign="top" align="left">Pointer to frame data (decompressed, de-unsynchronised)</td></tr>
  313.  <tr><td valign="top" align="right">+20</td><td valign="top" align="left">Frame data length</td></tr>
  314.  <tr><td valign="top" align="right">+24</td><td valign="top" align="left">Encryption type, or -1 if not given</td></tr>
  315.  <tr><td valign="top" align="right">+28</td><td valign="top" align="left">Compressed length, or -1 if not compressed</td></tr>
  316.  <tr><td valign="top" align="right">+32</td><td valign="top" align="left">Frame group, or -1 if not given</td></tr>
  317.  
  318. </table>
  319. </p>
  320.  
  321. <p>Flags will be promoted to those used by ID3v2.4, if they are of a lower
  322. version than that.</p>
  323. <p>Frame data will be terminated by a 0 (not included in the length) for
  324.    ease of decoding text fields.</p>
  325.  
  326. </dd></dl></dd></dl><hr><dl><dt><h2><a name="section_system_variables">System variables</a></h2></dt><dd><dl><dd><hr><h2 align="right"><a name="sysvar_amplayer_buffer_">AMPlayer$Buffer$*</a></h2><dd>Default AMPlayer output buffer sizes</dd><dt><h5>Use</h5></dt><dd>
  327. <p>When starting playback, AMPlayer checks the file being played against the
  328. variable
  329. <code>AMPlayer$Buffer$<i><part path></i></code>, where
  330. <i><part path></i> is the longest component of the path
  331. name which is set as a system variable. For example, if you were to play
  332. <code>ADFS::Music.$.Lennon.Imagine</code> and had the system
  333. variables <code>AMPlayer$Buffer$</code> and
  334. <code>AMPlayer$Buffer$ADFS</code> set, the latter would be used in
  335. preference to the former.
  336. </p>
  337.  
  338. <p>The value given is used to determine the number of 'blocks' of output
  339. data that will be buffered in the 'Antishock buffer'. The larger this buffer
  340. is, the longer the system can be busy before playback ceases. Larger buffers
  341. have a greater initial load on the machine as more data is decoded to fill
  342. the buffer when the first file is played.</p>
  343.  
  344. <p>A 'block' is an arbitrary size, currently around 4.5K. The reason for
  345. supplying a buffering value in blocks is to provide a more robust means of
  346. storing the buffering size. If in future the block size changes, the amount
  347. of time that that buffer corresponds to will remain constant (for a given
  348. frequency of data).</p>
  349.  
  350. <p>In the case of streams, the variable
  351. <code>AMPlayer$Buffer$Stream</code> will be used to determine the
  352. initial output buffer size.</p>
  353.  
  354. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_control-1">AMPlayer_Control 1</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="sysvar_amplayer_filebuffer">AMPlayer$FileBuffer</a></h2><dd>Input file buffer size</dd><dt><h5>Use</h5></dt><dd>
  355. <p>When starting playback, AMPlayer allocates a buffer for data from the
  356. file. Whereas <code>AMPlayer$Buffer$*</code> determines the output
  357. buffer size, <code>AMPlayer$FileBuffer</code> determines the input
  358. buffer size. If you are accessing files on a filing system which has a
  359. slow start up time, (for example networks or CDs) you may wish to set this
  360. higher value than the default.</p>
  361.  
  362. <p>The value this variable is set to is in Kilobytes. Unlike the output
  363. buffer, the input cannot be measured in blocks because that would require
  364. knowing in advance the data contained in the blocks.</p>
  365.  
  366. <p>For Streams <code>AMPlayer$FileBuffer</code> has no meaning and is
  367. not used.</p>
  368. </dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="sysvar_amplayer_volume">AMPlayer$Volume</a></h2><dd>Volume level to use when AMPlayer starts</dd><dt><h5>Use</h5></dt><dd>
  369. <p>When AMPlayer initialises, it reads <code>AMPlayer$Volume</code> to 
  370. determine the initial volume. This is a linear volume level, with a maximum
  371. at 127, a minimum at 0, and a default level of 112.</p>
  372.  
  373. <p>Whenever the volume level is changed in the base instance, this system
  374. variable is updated to reflect this. When an instance starts (in the same
  375. manner as the base AMPlayer instantiation intialising), it reads the state
  376. of <code>AMPlayer$Volume</code> and sets its volume to that specified.
  377. The result of this is that at any time that an instance is created it starts
  378. with the same volume level as the base instance. Should an instance wish
  379. to control the volume level of its instance, it should do so with care and
  380. pay attention to the initial volume level where appropriate. For example,
  381. if the user is playing their base instance at a volume level of 12, they
  382. will not wish to have a new instance playing at 112 unless they specifically
  383. requested it.</p>
  384. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_control-1">AMPlayer_Control 1</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="sysvar_amplayer_decimationthreshold">AMPlayer$DecimationThreshold</a></h2><dd>Select decimation threshold to use when AMPlayer starts</dd><dt><h5>Use</h5></dt><dd>
  385. <p>When AMPlayer initialises, it reads
  386. <code>AMPlayer$DecimationThreshold</code> to determine the initial
  387. decimation threshold. This threshold is used to determine during playback
  388. whether decimation of input data is used to provide output data.</p>
  389.  
  390. <p>Whenever the decimation threshold is changed in the base instance, this
  391. system variable is updated to reflect this. When an instance starts (in the
  392. same manner as the base AMPlayer instantiation intialising), it reads the
  393. state of <code>AMPlayer$DecimationThreshold</code> and sets its
  394. threshold to that specified. The result of this is that at any time that an
  395. instance is created it starts with the same threshold as the base
  396. instance.</p>
  397.  
  398. <p>When decimating input data, the upper half of the frequency data is
  399. discarded, resulting in a frequency of half that normally required for
  400. the input data. This reduces the processing required by the data, and
  401. therefore reduces the load that AMPlayer places on the system. This speed
  402. increase is to the detriment of the quality of the output data.</p>
  403. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_control-5">AMPlayer_Control 5</a></dd></dd></dl></dd></dl><hr><dl><dt><h2><a name="section_service_calls">Service calls</a></h2></dt><dd><dl><dd><hr><h2 align="right"><a name="service_amplayer">Service_AMPlayer</a><br>
  404.     (<acronym>Service &52E00</acronym>)</h2><dd>Events issued by AMPlayer</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to Service call" border="0">
  405.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">reason code :
  406.   <table summary="Opaque table of values" border="0"><tr><th align="right" valign="bottom">Reason</th><th align="left" valign="bottom">Meaning</th></tr>
  407.    <tr><td valign="top" align="right">0</td><td valign="top" align="left">
  408.     <a href="#service_amplayer-0">AMPlayer module is initialising</a>
  409.    </td></tr>
  410.    <tr><td valign="top" align="right">0</td><td valign="top" align="left">
  411.     <a href="#service_amplayer-0">AMPlayer module is initialising</a>
  412.    </td></tr>
  413.    <tr><td valign="top" align="right">1</td><td valign="top" align="left">
  414.     <a href="#service_amplayer-1">AMPlayer module is dying</a>
  415.    </td></tr>
  416.    <tr><td valign="top" align="right">2</td><td valign="top" align="left">
  417.     <a href="#service_amplayer-2">Playback is about to start</a>
  418.    </td></tr>
  419.    <tr><td valign="top" align="right">3</td><td valign="top" align="left">
  420.     <a href="#service_amplayer-3">Playback has stopped</a>
  421.    </td></tr>
  422.    <tr><td valign="top" align="right">4</td><td valign="top" align="left">
  423.     <a href="#service_amplayer-4">Playback has moved on to another track</a>
  424.    </td></tr>
  425.    <tr><td valign="top" align="right">5</td><td valign="top" align="left">
  426.     <a href="#service_amplayer-5">ID3v2 tag has been found</a>
  427.    </td></tr>
  428.    <tr><td valign="top" align="right">6</td><td valign="top" align="left">
  429.     <a href="#service_amplayer-6">One or more buffers previously passed to an AMPlayer have been marked as free</a>
  430.    </td></tr>
  431.   </table>
  432.  </td></tr>
  433.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">service call number</td></tr>
  434.  <tr><td valign="top" align="right">R2-R7</td><td valign="top">=</td><td valign="top" align="left">dependant on reason code</td></tr>
  435.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">instance handle of issuing instance, or 0 for
  436.                           the base</td></tr>
  437. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from Service call" border="0">
  438.  <tr><td valign="top" align="right">R1</td><td valign="top" align="left" colspan="2">preserved</td></tr>
  439. </table></dd><dt><h5>Use</h5></dt><dd>
  440. <p>Service_AMPlayer is issued by the AMPlayer module to inform clients of a
  441. change in state, or other information about playback. Consult the individual
  442. reason codes for more details.</p>
  443.  
  444. </dd><dt><h5>Related APIs</h5></dt><dd>None</dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="service_amplayer-0">Service_AMPlayer 0</a><br>
  445.     (<acronym>Service &52E00</acronym>)</h2><dd>AMPlayer module is initialising</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to Service call" border="0">
  446.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">reason code</td></tr>
  447.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">service call number</td></tr>
  448.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">instance handle of issuing instance, or 0 for
  449.                           the base</td></tr>
  450. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from Service call" border="0">
  451.  <tr><td valign="top" align="right">R1</td><td valign="top" align="left" colspan="2">preserved</td></tr>
  452. </table></dd><dt><h5>Use</h5></dt><dd>
  453. <p>Service_AMPlayer 0 is issued by the AMPlayer module when it initialises.
  454. Clients wishing to add plugins to the output of the module should register
  455. themselves.
  456. </p>
  457.  
  458. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_plugin">AMPlayer_Plugin</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="service_amplayer-1">Service_AMPlayer 1</a><br>
  459.     (<acronym>Service &52E00</acronym>)</h2><dd>AMPlayer module is dying</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to Service call" border="0">
  460.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">reason code</td></tr>
  461.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">service call number</td></tr>
  462.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">instance handle of issuing instance, or 0 for
  463.                           the base</td></tr>
  464. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from Service call" border="0">
  465.  <tr><td valign="top" align="right">R1</td><td valign="top" align="left" colspan="2">preserved</td></tr>
  466. </table></dd><dt><h5>Use</h5></dt><dd>
  467. <p>Service_AMPlayer 1 is issued by the AMPlayer module (or an instance of
  468. AMPlayer) when it is killed. Clients wishing to only run during the lifetime
  469. of AMPlayer should either become dormant or terminate. </p>
  470.  
  471. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_instance-2">AMPlayer_Instance 2</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="service_amplayer-2">Service_AMPlayer 2</a><br>
  472.     (<acronym>Service &52E00</acronym>)</h2><dd>Playback is about to start</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to Service call" border="0">
  473.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">reason code</td></tr>
  474.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">service call number</td></tr>
  475.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">instance handle of issuing instance, or 0 for
  476.                           the base</td></tr>
  477. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from Service call" border="0">
  478.  <tr><td valign="top" align="right">R1</td><td valign="top" align="left" colspan="2">preserved</td></tr>
  479. </table></dd><dt><h5>Use</h5></dt><dd>
  480. <p>Service_AMPlayer 2 is issued by the AMPlayer module when it is about to
  481. stat playing a track. Clients wishing to monitor the progress of the track
  482. in the background, or to schedule new tracks may wish to watch for this
  483. service.</p>
  484.  
  485. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_play">AMPlayer_Play</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="service_amplayer-3">Service_AMPlayer 3</a><br>
  486.     (<acronym>Service &52E00</acronym>)</h2><dd>Playback has stopped</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to Service call" border="0">
  487.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">reason code</td></tr>
  488.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">service call number</td></tr>
  489.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">instance handle of issuing instance, or 0 for
  490.                           the base</td></tr>
  491. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from Service call" border="0">
  492.  <tr><td valign="top" align="right">R1</td><td valign="top" align="left" colspan="2">preserved</td></tr>
  493. </table></dd><dt><h5>Use</h5></dt><dd>
  494. <p>Service_AMPlayer 3 is issued by the AMPlayer module when it has stopped
  495. playing and moved to state 'Dormant'.</p>
  496.  
  497. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_stop">AMPlayer_Stop</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="service_amplayer-4">Service_AMPlayer 4</a><br>
  498.     (<acronym>Service &52E00</acronym>)</h2><dd>Playback has moved on to another track</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to Service call" border="0">
  499.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">reason code</td></tr>
  500.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">service call number</td></tr>
  501.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">instance handle of issuing instance, or 0 for
  502.                           the base</td></tr>
  503. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from Service call" border="0">
  504.  <tr><td valign="top" align="right">R1</td><td valign="top" align="left" colspan="2">preserved</td></tr>
  505. </table></dd><dt><h5>Use</h5></dt><dd>
  506. <p>Service_AMPlayer 4 is issued by the AMPlayer module when it has changed
  507. to playing the next track queued. Clients wishing to track the file being
  508. played should watch for this service.</p>
  509.  
  510. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_play">AMPlayer_Play</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="service_amplayer-5">Service_AMPlayer 5</a><br>
  511.     (<acronym>Service &52E00</acronym>)</h2><dd>ID3v2 tag has been found</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to Service call" border="0">
  512.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">reason code</td></tr>
  513.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">service call number</td></tr>
  514.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">pointer to IDTag Information Block</td></tr>
  515.  <tr><td valign="top" align="right">R3</td><td valign="top">=</td><td valign="top" align="left">pointer to IDFrame Information Block</td></tr>
  516.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">instance handle of issuing instance, or 0 for
  517.                           the base</td></tr>
  518. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from Service call" border="0">
  519.  <tr><td valign="top" align="right">R1</td><td valign="top" align="left" colspan="2">preserved</td></tr>
  520. </table></dd><dt><h5>Use</h5></dt><dd>
  521. <p>Service_AMPlayer 5 is issued by the AMPlayer module during playback, when
  522. an ID3v2 tag has been encountered. Clients wishing to process ID3v2 as they
  523. arrive should watch for this service.</p>
  524.  
  525. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_control-3">AMPlayer_Control 3</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="service_amplayer-6">Service_AMPlayer 6</a><br>
  526.     (<acronym>Service &52E00</acronym>)</h2><dd>One or more buffers previously passed to an AMPlayer have been marked as free</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to Service call" border="0">
  527.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">reason code</td></tr>
  528.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">service call number</td></tr>
  529.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">stream handle</td></tr>
  530.  <tr><td valign="top" align="right">R3</td><td valign="top">=</td><td valign="top" align="left">flag word (currently 0)</td></tr>
  531.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">instance handle of issuing instance, or 0 for
  532.                           the base</td></tr>
  533. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from Service call" border="0">
  534.  <tr><td valign="top" align="right">R1</td><td valign="top" align="left" colspan="2">preserved</td></tr>
  535. </table></dd><dt><h5>Use</h5></dt><dd>
  536. <p>Service_AMPlayer 6 is issued by the AMPlayer module during playback from
  537. an AMPlayer stream for which service call reporting was requested at creation
  538. time when one or more blocks previously passed to that stream have been marked
  539. as being freed. Clients wishing to be informed when their blocks are no longer
  540. being held by the module should watch for this service.</p>
  541.  
  542. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_streamopen">AMPlayer_StreamOpen</a></dd></dd></dl></dd></dl><hr><dl><dt><h2><a name="section_swi_calls">SWI calls</a></h2></dt><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_play">AMPlayer_Play</a><br>
  543.     (<acronym>SWI &52E00</acronym>)</h2><dd>Plays or queues a file</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  544.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  545.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Name</th><th align="left" valign="bottom">Meaning</th></tr>
  546.    <tr><td valign="top" align="right">0</td><td valign="top">Queue</td><td valign="top" align="left" colspan="2">Places the named file in the queue of tracks
  547.                                 to play. If there is no file currently
  548.                                 playing, the behaviour is exactly as if bit
  549.                                 0 were clear.</td></tr>
  550.    <tr><td valign="top" align="right">1</td><td valign="top">Cue</td><td valign="top" align="left" colspan="2">Starts the named file immediately, but paused
  551.                               at the first frame. Use 
  552.                               <a href="#swi_amplayer_pause">AMPlayer_Pause</a>
  553.                               to start playback.</td></tr>
  554.    <tr><td valign="top" align="right">2</td><td valign="top">Transient</td><td valign="top" align="left" colspan="2">
  555.                               Creates a new instance, sets the volume level,
  556.                               marks the instance as transient,
  557.                               and starts the named file within that
  558.                               instance.</td></tr>
  559.    <tr><td valign="top" align="right">3-30</td><td valign="top"></td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  560.    <tr><td valign="top" align="right">31</td><td valign="top"></td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  561.                     should be directed.</td></tr>
  562.   </table>
  563.  </td></tr>
  564.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">pointer to filename</td></tr>
  565.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">if bit 2 of R0 set:<br>
  566.                           volume level to set, or -1 for default
  567.                           </td></tr>
  568.  <tr><td valign="top" align="right">R3</td><td valign="top">=</td><td valign="top" align="left">if bit 2 of R0 set:<br>
  569.                           pointer to instance name, or 0 to name
  570.                           automatically
  571.                           </td></tr>
  572.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  573.                           instance handle to direct at, or 0 for
  574.                           the base</td></tr>
  575. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  576.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">if bit 2 of R0 set:<br>
  577.                           handle of created instance
  578.                           </td></tr>
  579. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  580.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  581.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  582. <p>This SWI is used to play or queue a file for playback. When starting
  583. play transiently, the current play is unchaged and only the new instance
  584. is affected.</p>
  585.  
  586. </dd><dt><h5>Related * commands</h5></dt><dd><a href="#command_amplay">*AMPlay</a></dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_stop">AMPlayer_Stop</a>, <a href="#swi_amplayer_pause">AMPlayer_Pause</a>, <a href="#swi_amplayer_instance">AMPlayer_Instance</a>, <a href="#swi_amplayer_control-4">AMPlayer_Control 4</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_stop">AMPlayer_Stop</a><br>
  587.     (<acronym>SWI &52E01</acronym>)</h2><dd>Stops playback</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  588.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  589.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Name</th><th align="left" valign="bottom">Meaning</th></tr>
  590.    <tr><td valign="top" align="right">0</td><td valign="top">Cut</td><td valign="top" align="left" colspan="2">
  591.     Playback continues with the queued file if any. If no file is queued,
  592.     playback will stop.</td></tr>
  593.    <tr><td valign="top" align="right">1-30</td><td valign="top"></td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  594.    <tr><td valign="top" align="right">31</td><td valign="top"></td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  595.                     should be directed.</td></tr>
  596.   </table>
  597.  </td></tr>
  598.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  599.                           instance handle to direct at, or 0 for
  600.                           the base</td></tr>
  601. </table></dd><dt><h5>On exit</h5></dt><dd>None</dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  602.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  603.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  604. <p>This SWI is used to stop playback, or start the skip to the queued
  605. file.</p>
  606.  
  607. </dd><dt><h5>Related * commands</h5></dt><dd><a href="#command_amstop">*AMStop</a></dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_play">AMPlayer_Play</a>, <a href="#swi_amplayer_pause">AMPlayer_Pause</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_pause">AMPlayer_Pause</a><br>
  608.     (<acronym>SWI &52E02</acronym>)</h2><dd>Pauses playback</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  609.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  610.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Name</th><th align="left" valign="bottom">Meaning</th></tr>
  611.    <tr><td valign="top" align="right">0</td><td valign="top">Resume</td><td valign="top" align="left" colspan="2">
  612.     Resumes playback.</td></tr>
  613.    <tr><td valign="top" align="right">1-30</td><td valign="top"></td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  614.    <tr><td valign="top" align="right">31</td><td valign="top"></td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  615.                     should be directed.</td></tr>
  616.   </table>
  617.  </td></tr>
  618.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  619.                           instance handle to direct at, or 0 for
  620.                           the base</td></tr>
  621. </table></dd><dt><h5>On exit</h5></dt><dd>None</dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  622.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  623.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  624. <p>This SWI is used to pause or resume playback. When paused, decoding to
  625. the output buffer continues, but at a much reduced rate. There is no sound
  626. output.</p>
  627.  
  628. <p>Pause mode may also be cancelled by stopping. If 
  629. <a href="#swi_amplayer_stop">AMPlayer_Stop</a> is used to
  630. cut to the next file, or if a different file is started, pause mode will
  631. continue to be in effect, freezing the new file at the start of the file.
  632. This can be used to ensure that playback starts at the instant of calling
  633. AMPlayer_Pause (as opposed to calling 
  634. <a href="#swi_amplayer_play">AMPlayer_Play</a>, which can have a delay while
  635. opening the file etc).</p>
  636.  
  637. </dd><dt><h5>Related * commands</h5></dt><dd><a href="#command_ampause">*AMPause</a></dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_play">AMPlayer_Play</a>, <a href="#swi_amplayer_stop">AMPlayer_Stop</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_locate">AMPlayer_Locate</a><br>
  638.     (<acronym>SWI &52E03</acronym>)</h2><dd>Locates a position in the playback</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  639.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  640.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  641.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  642.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  643.                     should be directed.</td></tr>
  644.   </table>
  645.  </td></tr>
  646.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">target time in centi-seconds</td></tr>
  647.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  648.                           instance handle to direct at, or 0 for
  649.                           the base</td></tr>
  650. </table></dd><dt><h5>On exit</h5></dt><dd>None</dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  651.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  652.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  653. <p>This SWI locates the position of the target time, and continues playback
  654. (or pausing) from there. This has no effect unless the status is either
  655. Playing, Locating or Paused. This may take some time, and the playback
  656. buffer may empty (which will mute the sound).</p>
  657.  
  658. <p>The time given here corresponds to the elapsed time returned from
  659. <a href="#swi_amplayer_info">AMPlayer_Info</a>. This is true even when the
  660. elapsed time is wrong. So when, at time X, the Info call returns the wrong
  661. time Y, giving time Y to this call will still start playing at the right
  662. time X.</p>
  663.  
  664. <p>Playback can only start on a frame boundary, so the resolution of the
  665. start point is around 2 cs (for 128kbit/sec, 44.1kHz frames).</p>
  666.  
  667. </dd><dt><h5>Related * commands</h5></dt><dd><a href="#command_amlocate">*AMLocate</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_info">AMPlayer_Info</a><br>
  668.     (<acronym>SWI &52E04</acronym>)</h2><dd>Return information on the state of playback</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  669.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  670.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  671.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  672.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  673.                     should be directed.</td></tr>
  674.   </table>
  675.  </td></tr>
  676.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  677.                           instance handle to direct at, or 0 for
  678.                           the base</td></tr>
  679. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  680.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">Player status :
  681.   <table summary="Opaque table of values" border="0"><tr><th align="right" valign="bottom">State</th><th align="left" valign="bottom">Meaning and registers</th></tr>
  682.    <tr><td valign="top" align="right">0</td><td valign="top" align="left">Dormant<br>
  683.                      R1 - R4 preserved</td></tr>
  684.    <tr><td valign="top" align="right">1</td><td valign="top" align="left">Starting<br>
  685.                      R1 = pointer to filename<br>
  686.                      R2 - R4 preserved</td></tr>
  687.    <tr><td valign="top" align="right">2</td><td valign="top" align="left">Locating<br>
  688.                      R1 = pointer to filename<br>
  689.                      R2 = pointer to <a href="#subsubsection_file_information_block">File Information Block</a>, or 0 if not set up yet<br>
  690.                      R3 = pointer to <a href="#subsubsection_frame_information_block">Frame Information Block</a>, or 0 if not set up yet<br>
  691.                      R4 = target time</td></tr>
  692.    <tr><td valign="top" align="right">3</td><td valign="top" align="left">Playing<br>
  693.                      R1 = pointer to filename<br>
  694.                      R2 = pointer to <a href="#subsubsection_file_information_block">File Information Block</a>, or 0 if not set up yet<br>
  695.                      R3 = pointer to <a href="#subsubsection_frame_information_block">Frame Information Block</a>, or 0 if not set up yet<br>
  696.                      R4 preserved</td></tr>
  697.    <tr><td valign="top" align="right">4</td><td valign="top" align="left">Pausing<br>
  698.                      R1 = pointer to filename<br>
  699.                      R2 = pointer to <a href="#subsubsection_file_information_block">File Information Block</a>, or 0 if not set up yet<br>
  700.                      R3 = pointer to <a href="#subsubsection_frame_information_block">Frame Information Block</a>, or 0 if not set up yet<br>
  701.                      R4 preserved</td></tr>
  702.    <tr><td valign="top" align="right">5</td><td valign="top" align="left">Stopping<br>
  703.                      R1 = pointer to filename<br>
  704.                      R2 - R4 preserved</td></tr>
  705.    <tr><td valign="top" align="right">6</td><td valign="top" align="left">Changing<br>
  706.                      R1 = pointer to filename<br>
  707.                      R2 - R4 preserved</td></tr>
  708.    <tr><td valign="top" align="right">7</td><td valign="top" align="left">Cueing<br>
  709.                      R1 = pointer to filename<br>
  710.                      R2 - R4 preserved</td></tr>
  711.   </table>
  712.  </td></tr>
  713. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  714.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  715.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  716. <p>This call will return information about the current state of the
  717. player.</p>
  718.  
  719. <p>When locating, the current time can be read from the file info block, as
  720. it moves toward the target time returned in R4.</p>
  721.  
  722. <p>This call might be made from BASIC with :</p>
  723.  
  724. <p>
  725. <tt><b>SYS "AMPlayer_Info",,"" TO ,Filename$,FIB%</b></tt>
  726. </p>
  727.  
  728. <p>This will set Filename$ to either "" or the filename. Similarily, FIB%
  729. will be 0 if there is no info at this stage, or a pointer to it if there
  730. is.</p>
  731.  
  732. <p>There is a brief period when the status might be returned as Locating (2) or Playing (3), but where there is no valid FIB, because the first frame has yet to be read.</p>
  733.  
  734. </dd><dt><h5>Related * commands</h5></dt><dd><a href="#command_aminfo">*AMInfo</a></dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_fileinfo">AMPlayer_FileInfo</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_control">AMPlayer_Control</a><br>
  735.     (<acronym>SWI &52E05</acronym>)</h2><dd>Configure the operation of the player</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  736.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  737.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  738.    <tr><td valign="top" align="right">0-7</td><td valign="top" align="left" colspan="2">reason code :
  739.      <table summary="Opaque table of values" border="0"><tr><th align="right" valign="bottom">Reason</th><th align="left" valign="bottom">Configuration</th></tr>
  740.       <tr><td valign="top" align="right">0</td><td valign="top" align="left">
  741.        <a href="#swi_amplayer_control-0">Read or write the volume level</a>
  742.       </td></tr>
  743.       <tr><td valign="top" align="right">1</td><td valign="top" align="left">
  744.        <a href="#swi_amplayer_control-1">Read or write the output buffer size</a>
  745.       </td></tr>
  746.       <tr><td valign="top" align="right">2</td><td valign="top" align="left">
  747.        <a href="#swi_amplayer_control-2">Set SVC stack check level</a>
  748.       </td></tr>
  749.       <tr><td valign="top" align="right">3</td><td valign="top" align="left">
  750.        <a href="#swi_amplayer_control-3">Control the ID3v2 tag processing facilities</a>
  751.       </td></tr>
  752.       <tr><td valign="top" align="right">4</td><td valign="top" align="left">
  753.        <a href="#swi_amplayer_control-4">Read or write the 'transience' flag</a>
  754.       </td></tr>
  755.       <tr><td valign="top" align="right">5</td><td valign="top" align="left">
  756.        <a href="#swi_amplayer_control-5">Read or write the decimation threshold</a>
  757.       </td></tr>
  758.      </table>
  759.     </td></tr>
  760.    <tr><td valign="top" align="right">8-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  761.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  762.                     should be directed.</td></tr>
  763.   </table>
  764.  </td></tr>
  765.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  766.                           instance handle to direct at, or 0 for
  767.                           the base</td></tr>
  768. </table></dd><dt><h5>On exit</h5></dt><dd>None</dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  769.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  770.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  771. <p>This SWI is used to configure various aspects of the AMPlayer module's
  772. operation.</p>
  773.  
  774. </dd><dt><h5>Related APIs</h5></dt><dd>None</dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_control-0">AMPlayer_Control 0</a><br>
  775.     (<acronym>SWI &52E05</acronym>)</h2><dd>Read or write the volume level</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  776.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  777.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  778.    <tr><td valign="top" align="right">0-7</td><td valign="top" align="left" colspan="2">0 (reason code)</td></tr>
  779.    <tr><td valign="top" align="right">8-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  780.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  781.                     should be directed.</td></tr>
  782.   </table>
  783.  </td></tr>
  784.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">new volume level (0-127), or -1 to read
  785.                           current level</td></tr>
  786.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  787.                           instance handle to direct at, or 0 for
  788.                           the base</td></tr>
  789. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  790.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">old volume level</td></tr>
  791. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  792.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  793.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  794. <p>This SWI is used to read or write the main volume level of the
  795. player.</p>
  796.  
  797. </dd><dt><h5>Related * commands</h5></dt><dd><a href="#command_amvolume">*AMVolume</a></dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_control">AMPlayer_Control</a></dd><dt><h5>Related system variables</h5></dt><dd><a href="#sysvar_amplayer_volume">AMPlayer$Volume</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_control-1">AMPlayer_Control 1</a><br>
  798.     (<acronym>SWI &52E05</acronym>)</h2><dd>Read or write the output buffer size</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  799.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  800.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  801.    <tr><td valign="top" align="right">0-7</td><td valign="top" align="left" colspan="2">1 (reason code)</td></tr>
  802.    <tr><td valign="top" align="right">8</td><td valign="top" align="left" colspan="2">Use blocks, rather than bytes</td></tr>
  803.    <tr><td valign="top" align="right">9-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  804.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  805.                     should be directed.</td></tr>
  806.   </table>
  807.  </td></tr>
  808.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">new buffer size in bytes or blocks, or -1 to read
  809.                           current size</td></tr>
  810.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  811.                           instance handle to direct at, or 0 for
  812.                           the base</td></tr>
  813. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  814.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">old size in bytes or blocks</td></tr>
  815. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  816.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  817.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  818. <p>This control call is used to read or write the size of the audio buffer
  819. used by AMPlayer to store decoded data. The size can be specified in bytes
  820. or in blocks. It is recommended that you use the blocks size to be
  821. compatible with the system variable usage, and to ensure that similar
  822. amounts of data are buffered in future.</p>
  823.  
  824. <p>If the buffer isn't currently created, this controls how large it will be
  825. when it eventually is. If it exists, OS_ChangeDynamicArea is used to change
  826. the size. This may fail with an error, even if some of the job was done
  827. (this can happen when reducing the size, as the amount that can be released
  828. depends on what is currently being played). This effect is greatly reduced
  829. in AMPlayer 1.29 and later.</p>
  830.  
  831. <p>If it succeeds, the sound may be broken up slightly. On versions of
  832. AMPlayer prior to 1.29, this will always cause at least one 'jump' in the
  833. playback.</p>
  834.  
  835. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_control">AMPlayer_Control</a></dd><dt><h5>Related system variables</h5></dt><dd><a href="#sysvar_amplayer_buffer_">AMPlayer$Buffer$*</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_control-2">AMPlayer_Control 2</a><br>
  836.     (<acronym>SWI &52E05</acronym>)</h2><dd>Set SVC stack check level</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  837.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  838.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  839.    <tr><td valign="top" align="right">0-7</td><td valign="top" align="left" colspan="2">2 (reason code)</td></tr>
  840.    <tr><td valign="top" align="right">8-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  841.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  842.                     should be directed.</td></tr>
  843.   </table>
  844.  </td></tr>
  845.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">new level (in words), or 0 for default
  846.  </td></tr>
  847.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  848.                           instance handle to direct at, or 0 for
  849.                           the base</td></tr>
  850. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  851.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">old level</td></tr>
  852. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  853.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  854.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  855. <p>This SWI call is used to set the stack check level used when a callback
  856. occurs</p>
  857.  
  858. <p>When receiving a callback, the SVC stack depth is checked to see if the
  859. kernel is reasonably unthreaded. By using this call, you can control what is
  860. considered "reasonable". The default value is currently 64, i.e. if there
  861. are more than 64 words on the stack by the time of the callback, a new
  862. callback will be registered later instead. Setting this too low will cause
  863. the player to stall, and you can only stop it by killing the module (or
  864. putting the level back up).</p>
  865.  
  866. <p>It is not expected that users of the AMPlayer API will need to use this
  867. SWI.</p>
  868.  
  869. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_control">AMPlayer_Control</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_control-3">AMPlayer_Control 3</a><br>
  870.     (<acronym>SWI &52E05</acronym>)</h2><dd>Control the ID3v2 tag processing facilities</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  871.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  872.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  873.    <tr><td valign="top" align="right">0-7</td><td valign="top" align="left" colspan="2">3 (reason code)</td></tr>
  874.    <tr><td valign="top" align="right">8-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  875.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  876.                     should be directed.</td></tr>
  877.   </table>
  878.  </td></tr>
  879.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">sub-reason code :
  880.   <table summary="Opaque table of values" border="0"><tr><th align="right" valign="bottom">Sub-reason</th><th align="left" valign="bottom">Meaning</th></tr>
  881.    <tr><td valign="top" align="right">0</td><td valign="top" align="left">
  882.     <a href="#swi_amplayer_control-3-_0">Enable or disable ID3v2 processing</a>
  883.    </td></tr>
  884.    <tr><td valign="top" align="right">1</td><td valign="top" align="left">
  885.     <a href="#swi_amplayer_control-3-_1">Select ID3v2 frame filtering</a>
  886.    </td></tr>
  887.   </table>
  888.  </td></tr>
  889.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  890.                           instance handle to direct at, or 0 for
  891.                           the base</td></tr>
  892. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  893.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">old level</td></tr>
  894. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  895.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  896.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  897. <p>This control call is used to control ID3v2 processing within the player.
  898. </p>
  899.  
  900. <p>ID3v2 processing is quite intensive and can have a performance hit,
  901. especially when compressed frames are used.</p>
  902.  
  903. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_control-3">AMPlayer_Control 3</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_control-3-_0">AMPlayer_Control 3, 0</a><br>
  904.     (<acronym>SWI &52E05</acronym>)</h2><dd>Enable or disable ID3v2 processing</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  905.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  906.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  907.    <tr><td valign="top" align="right">0-7</td><td valign="top" align="left" colspan="2">3 (reason code)</td></tr>
  908.    <tr><td valign="top" align="right">8-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  909.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  910.                     should be directed.</td></tr>
  911.   </table>
  912.  </td></tr>
  913.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">0 (sub-reason code)</td></tr>
  914.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">type of change :
  915.   <table summary="Opaque table of values" border="0"><tr><th align="right" valign="bottom">Type</th><th align="left" valign="bottom">Meaning</th></tr>
  916.    <tr><td valign="top" align="right">0</td><td valign="top" align="left">disable</td></tr>
  917.    <tr><td valign="top" align="right">1</td><td valign="top" align="left">enable</td></tr>
  918.    <tr><td valign="top" align="right">-1</td><td valign="top" align="left">read current state</td></tr>
  919.   </table>
  920.  </td></tr>
  921.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  922.                           instance handle to direct at, or 0 for
  923.                           the base</td></tr>
  924. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  925.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">enable count, or 0 if disabled</td></tr>
  926. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  927.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  928.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  929. <p>This SWI is used to enable or disable the processing of ID3v2 tags by the
  930. AMPlayer module.</p>
  931.  
  932. <p>When disabled, no ID3v2 processing at all is performed - the tags are
  933. merely skipped. This will improve performance when such tags are
  934. encountered.</p>
  935.  
  936. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_control-3">AMPlayer_Control 3</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_control-3-_1">AMPlayer_Control 3, 1</a><br>
  937.     (<acronym>SWI &52E05</acronym>)</h2><dd>Select ID3v2 frame filtering</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  938.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  939.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  940.    <tr><td valign="top" align="right">0-7</td><td valign="top" align="left" colspan="2">3 (reason code)</td></tr>
  941.    <tr><td valign="top" align="right">8-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  942.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  943.                     should be directed.</td></tr>
  944.   </table>
  945.  </td></tr>
  946.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">1 (sub-reason code)</td></tr>
  947.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">pointer to frame name, or 0 for 'all frames'
  948.  </td></tr>
  949.  <tr><td valign="top" align="right">R3</td><td valign="top">=</td><td valign="top" align="left">filtering operation :
  950.   <table summary="Opaque table of values" border="0"><tr><th align="right" valign="bottom">Type</th><th align="left" valign="bottom">Meaning</th></tr>
  951.    <tr><td valign="top" align="right">0</td><td valign="top" align="left">disable frame processing</td></tr>
  952.    <tr><td valign="top" align="right">1</td><td valign="top" align="left">enable frame processing</td></tr>
  953.    <tr><td valign="top" align="right">-1</td><td valign="top" align="left">read current state of processing</td></tr>
  954.    <tr><td valign="top" align="right">-2</td><td valign="top" align="left">read frame state as matched by processing engine
  955.    </td></tr>
  956.   </table>
  957.  </td></tr>
  958.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  959.                           instance handle to direct at, or 0 for
  960.                           the base</td></tr>
  961. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  962.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">enable count, or 0 if disabled</td></tr>
  963. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  964.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  965.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  966. <p>This SWI is used to enable or disable specific frames or groups of frames for processing through the service interface.</p>
  967.  
  968. <p>A single character frame name will select all frames starting with that
  969. character. Three character frame names select the ID3v2.2 and earlier frames
  970. that match. Four character frame names select the ID3v2.3 and ID3v2.4 frame
  971. explicitly.</p>
  972.  
  973. <p>Claimants of the ID3v2 service should enable the frames they wish to see,
  974. and disable them when they no longer require them.</p>
  975.  
  976. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_control-3">AMPlayer_Control 3</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_control-4">AMPlayer_Control 4</a><br>
  977.     (<acronym>SWI &52E05</acronym>)</h2><dd>Read or write the 'transience' flag</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  978.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  979.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  980.    <tr><td valign="top" align="right">0-7</td><td valign="top" align="left" colspan="2">4 (reason code)</td></tr>
  981.    <tr><td valign="top" align="right">8-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  982.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  983.                     should be directed.</td></tr>
  984.   </table>
  985.  </td></tr>
  986.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">Operation to apply:
  987.                            <table summary="Opaque table of values" border="0"><tr><th align="right" valign="bottom">Value</th><th align="left" valign="bottom">Meaning</th></tr>
  988.                             <tr><td valign="top" align="right">0</td><td valign="top" align="left">Mark as intransient</td></tr>
  989.                             <tr><td valign="top" align="right">1</td><td valign="top" align="left">Mark as transient</td></tr>
  990.                             <tr><td valign="top" align="right">-1</td><td valign="top" align="left">Read current flag</td></tr>
  991.                            </table>
  992.                           </td></tr>
  993.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  994.                           instance handle to direct at, or 0 for
  995.                           the base</td></tr>
  996. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  997.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">old transience flag</td></tr>
  998. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  999.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1000.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1001. <p>This SWI is used to read or write the transiency flag for an instance.
  1002. Transiency has no meaning for the base instance, but for created instances,
  1003. it means that when playback completes, the instance will be destroyed
  1004. automatically.</p>
  1005.  
  1006. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_control-3">AMPlayer_Control 3</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_control-5">AMPlayer_Control 5</a><br>
  1007.     (<acronym>SWI &52E05</acronym>)</h2><dd>Read or write the decimation threshold</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1008.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1009.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1010.    <tr><td valign="top" align="right">0-7</td><td valign="top" align="left" colspan="2">5 (reason code)</td></tr>
  1011.    <tr><td valign="top" align="right">8-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1012.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1013.                     should be directed.</td></tr>
  1014.   </table>
  1015.  </td></tr>
  1016.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">Operation to apply:
  1017.                            <table summary="Opaque table of values" border="0"><tr><th align="right" valign="bottom">Value</th><th align="left" valign="bottom">Meaning</th></tr>
  1018.                             <tr><td valign="top" align="right">0</td><td valign="top" align="left">Read decimation threshold</td></tr>
  1019.                             <tr><td valign="top" align="right">1</td><td valign="top" align="left">Set decimation threshold</td></tr>
  1020.                            </table>
  1021.                           </td></tr>
  1022.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">new decimation threshold</td></tr>
  1023.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1024.                           instance handle to direct at, or 0 for
  1025.                           the base</td></tr>
  1026. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  1027.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">current decimation threshold</td></tr>
  1028. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1029.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1030.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1031. <p>This SWI is used to read or write the 'decimation threshold'. AMPlayer
  1032. will normally decode data at full accuracy. If the 'decimation threshold'
  1033. frequency is met or exceeded, the module will apply automatic decimation
  1034. to the output.</p>
  1035.  
  1036. <p>The initial decimation value is based on the version of the module in
  1037. use (for AMPlayer, this is 1000000, for AMPlayerFP, it is
  1038. 22050, and for AMPlayer6 it is 0). This can be overridden by setting the
  1039. <code>AMPlayer$DecimationThreshold</code> variable to a number before
  1040. starting the module. Setting the decimation threshold of the base instance
  1041. will set the variable to the same value.
  1042. </p>
  1043.  
  1044. <p>On builds that do not support decimation, the calls are ignored, and
  1045. reading the decimation always returns 1000000.
  1046. </p>
  1047.  
  1048. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_control">AMPlayer_Control</a></dd><dt><h5>Related system variables</h5></dt><dd><a href="#sysvar_amplayer_decimationthreshold">AMPlayer$DecimationThreshold</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_plugin">AMPlayer_Plugin</a><br>
  1049.     (<acronym>SWI &52E06</acronym>)</h2><dd>Plugin operations</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1050.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1051.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1052.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1053.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1054.                     should be directed.</td></tr>
  1055.   </table>
  1056.  </td></tr>
  1057.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">reason code :
  1058.   <table summary="Opaque table of values" border="0"><tr><th align="right" valign="bottom">Value</th><th align="left" valign="bottom">Meaning</th></tr>
  1059.    <tr><td valign="top" align="right">0</td><td valign="top" align="left">Register plugin</td></tr>
  1060.    <tr><td valign="top" align="right">1</td><td valign="top" align="left">Deregister plugin</td></tr>
  1061.   </table>
  1062.  </td></tr>
  1063.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">private word to pass in R0</td></tr>
  1064.  <tr><td valign="top" align="right">R3</td><td valign="top">=</td><td valign="top" align="left">pointer to <a href="#entry_plugin_preprocess">pre-processor (pre-DCT)</a>, or 0 for none
  1065.  </td></tr>
  1066.  <tr><td valign="top" align="right">R4</td><td valign="top">=</td><td valign="top" align="left">pointer to <a href="#entry_plugin_postprocess">post-processor (post-DCT)</a>, or 0 for
  1067.  none</td></tr>
  1068.  <tr><td valign="top" align="right">R5</td><td valign="top">=</td><td valign="top" align="left">pointer to static
  1069.    <a href="#subsubsection_plugin_information_block">Plugin Information Block</a>
  1070.  </td></tr>
  1071.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1072.                           instance handle to direct at, or 0 for
  1073.                           the base</td></tr>
  1074. </table></dd><dt><h5>On exit</h5></dt><dd>None</dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1075.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1076.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1077. <p>This SWI is used to register or deregister plugins.</p>
  1078. </dd><dt><h5>Related APIs</h5></dt><dd>None</dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_fileinfo">AMPlayer_FileInfo</a><br>
  1079.     (<acronym>SWI &52E07</acronym>)</h2><dd>Return information on the a file</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1080.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags for requested information, or 0 to return
  1081.                           size of buffers :
  1082.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1083.    <tr><td valign="top" align="right">0</td><td valign="top" align="left" colspan="2">Return total time, and Frame Information Block for the
  1084.                    first frame</td></tr>
  1085.    <tr><td valign="top" align="right">1</td><td valign="top" align="left" colspan="2">Reserved, must be 0</td></tr>
  1086.    <tr><td valign="top" align="right">2</td><td valign="top" align="left" colspan="2">Return ID3 tag information</td></tr>
  1087.    <tr><td valign="top" align="right">3-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1088.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1089.                     should be directed.</td></tr>
  1090.   </table>
  1091.  </td></tr>
  1092.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">pointer to filename</td></tr>
  1093.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">pointer to buffer for
  1094.   <a href="#subsubsection_file_information_block">File Information Block</a>
  1095.   </td></tr>
  1096.  <tr><td valign="top" align="right">R3</td><td valign="top">=</td><td valign="top" align="left">pointer to buffer for 
  1097.   <a href="#subsubsection_frame_information_block">Frame Information Block</a>
  1098.   </td></tr>
  1099.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1100.                           instance handle to direct at, or 0 for
  1101.                           the base</td></tr>
  1102. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  1103.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">required size of the File Information Buffer, if
  1104.                           reading size of buffer</td></tr>
  1105.  <tr><td valign="top" align="right">R3</td><td valign="top">=</td><td valign="top" align="left">required size of the Frame Information Buffer, if
  1106.                           reading size of buffer</td></tr>
  1107. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1108.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1109.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1110. <p>This SWI attempts to return useful information about the file given. The
  1111. more bits you set in R0, the slower it gets, as it requires more of the file
  1112. to be read. In particular, requesting the ID3 tag information means seeking
  1113. to the end of the file, which may be very slow on some filing systems (like
  1114. DATFS).</p>
  1115.  
  1116. <p>Therefore, it sometimes makes sense to make 3 calls:
  1117.  
  1118. <ol><li>With R0=&000, to get the size of the buffers.</li><li>With R0=&001, to read the quick things and determine whether the file
  1119.    is interesting at all.</li><li>With R0=&004, to read only the ID3 tag fields.</li></ol>
  1120. </p>
  1121.  
  1122. <p>Remember to read the buffer sizes first. These information blocks will no
  1123. doubt be extended, and if you assume the old size, your program will stop
  1124. working when a new AMPlayer module comes out. Just read the size, and your
  1125. program will continue to work for eternity. You don't need to supply a frame
  1126. info pointer in R3 unless bit 0 is set.</p>
  1127.  
  1128. </dd><dt><h5>Related * commands</h5></dt><dd><a href="#command_aminfo">*AMInfo</a></dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_info">AMPlayer_Info</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_streamopen">AMPlayer_StreamOpen</a><br>
  1129.     (<acronym>SWI &52E08</acronym>)</h2><dd>Starts a stream playing</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1130.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1131.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Name</th><th align="left" valign="bottom">Meaning</th></tr>
  1132.    <tr><td valign="top" align="right">0</td><td valign="top">Queue</td><td valign="top" align="left" colspan="2">Places the named file in the queue of tracks
  1133.                                 to play. If there is no file currently
  1134.                                 playing, the behaviour is exactly as if bit
  1135.                                 0 were clear.</td></tr>
  1136.    <tr><td valign="top" align="right">1</td><td valign="top">Cue</td><td valign="top" align="left" colspan="2">Starts the named file immediately, but paused
  1137.                               at the first frame. Use 
  1138.                               <a href="#swi_amplayer_pause">AMPlayer_Pause</a>
  1139.                               to start playback.</td></tr>
  1140.    <tr><td valign="top" align="right">2</td><td valign="top">GenerateService</td><td valign="top" align="left" colspan="2">Indicates that 
  1141.                               <a href="#service_amplayer-6">Service_AMPlayer 6</a>
  1142.                               should be generated every time one or more
  1143.                               blocks passed into the stream become free.
  1144.                               </td></tr>
  1145.    <tr><td valign="top" align="right">3-30</td><td valign="top"></td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1146.    <tr><td valign="top" align="right">31</td><td valign="top"></td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1147.                     should be directed.</td></tr>
  1148.   </table>
  1149.  </td></tr>
  1150.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">pointer to stream name (for information)
  1151.  </td></tr>
  1152.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1153.                           instance handle to direct at, or 0 for
  1154.                           the base</td></tr>
  1155. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  1156.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">stream handle, or 0 if failed to
  1157.                           start</td></tr>
  1158. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1159.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1160.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1161. <p>This SWI is used to start streamed input, ready for playback.</p>
  1162.  
  1163. <p>Called by a streaming application to get a Stream Handle.
  1164. Most streamers will start the stream paused and feed data in until the
  1165. buffer full flag (see <a href="#swi_amplayer_streaminfo">AMPlayer_StreamInfo</a>)
  1166. is set.</p>
  1167.  
  1168. <p>Note: The combination of Queue and Start Paused may not work.</p>
  1169.  
  1170. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_play">AMPlayer_Play</a>, <a href="#swi_amplayer_streamclose">AMPlayer_StreamClose</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_streamclose">AMPlayer_StreamClose</a><br>
  1171.     (<acronym>SWI &52E09</acronym>)</h2><dd>Informs AMPlayer that a stream has ended</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1172.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1173.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1174.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1175.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1176.                     should be directed.</td></tr>
  1177.   </table>
  1178.  </td></tr>
  1179.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">stream handle</td></tr>
  1180.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1181.                           instance handle to direct at, or 0 for
  1182.                           the base</td></tr>
  1183. </table></dd><dt><h5>On exit</h5></dt><dd>None</dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1184.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1185.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1186. <p>This SWI is used to inform the AMPlayer module that no more data will be
  1187. supplied to the stream. This does NOT release outstanding buffers that have
  1188. been passed to AMPlayer. If you need to get these back, call
  1189. AMPlayer_StreamClose, then <a href="#swi_amplayer_stop">AMPlayer_Stop</a>.
  1190. </p>
  1191.  
  1192. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_streamopen">AMPlayer_StreamOpen</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_streamgivedata">AMPlayer_StreamGiveData</a><br>
  1193.     (<acronym>SWI &52E0A</acronym>)</h2><dd>Inform AMPlayer of the location of input data</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1194.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1195.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1196.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1197.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1198.                     should be directed.</td></tr>
  1199.   </table>
  1200.  </td></tr>
  1201.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">stream handle</td></tr>
  1202.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">pointer to streaming data block :
  1203.   <table summary="Opaque table of offset/contents" border="0"><tr><th align="right" valign="bottom">Offset</th><th align="left" valign="bottom">Contents</th></tr>
  1204.    <tr><td valign="top" align="right">+0</td><td valign="top" align="left">Usage word</td></tr>
  1205.    <tr><td valign="top" align="right">+4</td><td valign="top" align="left">Meta data list associated with this buffer, or 0
  1206.                       for no data</td></tr>
  1207.    <tr><td valign="top" align="right">+8</td><td valign="top" align="left">Length of data following</td></tr>
  1208.   </table>
  1209.  </td></tr>
  1210.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1211.                           instance handle to direct at, or 0 for
  1212.                           the base</td></tr>
  1213. </table></dd><dt><h5>On exit</h5></dt><dd>None</dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1214.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1215.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1216. <p>Called by a streamer application to pass a block of data to AMPlayer. All
  1217. but the first word may be considered read-only and must be in interrupt
  1218. sharable space (i.e. in a dynamic area, module area, sprite pool etc, NOT in
  1219. the application). By calling this SWI, the application must guarantee that
  1220. it will keep the buffer around (and unchanged) at least until AMPlayer sets
  1221. the usage word to zero.</p>
  1222.  
  1223. <p>The streamer application should monitor the first word of the buffers it
  1224. has previously passed in to see when it gets set to 0 to allow reuse.
  1225. Buffers will be released strictly in the same order they were passed in.</p>
  1226.         
  1227. <p>The metadata list blocks must be kept intact for the same length of time
  1228. as the data blocks, and can be considered 'released' by AMPlayer when their
  1229. corresponding data blocks are.</p>
  1230.         
  1231. <p>Metadata blocks are in the following format:
  1232.  
  1233. <table summary="Opaque table of offset/contents" border="0"><tr><th align="right" valign="bottom">Offset</th><th align="left" valign="bottom">Contents</th></tr>
  1234. <tr><td valign="top" align="right">+0</td><td valign="top" align="left">Pointer to next metadata block, or 0 for the last
  1235.                    entry</td></tr>
  1236. <tr><td valign="top" align="right">+4</td><td valign="top" align="left">Pointer to a 0-terminated 'Key name' field</td></tr>
  1237. <tr><td valign="top" align="right">+8</td><td valign="top" align="left">Pointer to a value field (often a 0-terminated string,
  1238.                    but may be binary data)</td></tr>
  1239. <tr><td valign="top" align="right">+12</td><td valign="top" align="left">Length of value buffer in bytes</td></tr>
  1240. </table>
  1241. </p>
  1242.  
  1243. <p>It is envisaged that there will be a SWI added later to allow metadata to
  1244. be supplied for non-streaming sources.</p>
  1245.  
  1246. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_streamopen">AMPlayer_StreamOpen</a>, <a href="#swi_amplayer_streamclose">AMPlayer_StreamClose</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_streaminfo">AMPlayer_StreamInfo</a><br>
  1247.     (<acronym>SWI &52E0B</acronym>)</h2><dd>Read information about the streaming data</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1248.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1249.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1250.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1251.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1252.                     should be directed.</td></tr>
  1253.   </table>
  1254.  </td></tr>
  1255.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">stream handle</td></tr>
  1256.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1257.                           instance handle to direct at, or 0 for
  1258.                           the base</td></tr>
  1259. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  1260.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags word :
  1261.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1262.    <tr><td valign="top" align="right">0</td><td valign="top" align="left" colspan="2">Stream is active (actively being processed)</td></tr>
  1263.    <tr><td valign="top" align="right">1</td><td valign="top" align="left" colspan="2">Output buffer has been full</td></tr>
  1264.    <tr><td valign="top" align="right">2</td><td valign="top" align="left" colspan="2">Stream is paused</td></tr>
  1265.   </table>
  1266.  </td></tr>
  1267. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1268.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1269.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1270. <p>This SWI is called by a streaming application to monitor the state of the
  1271. decoder. Typically a streamer will start a stream up paused and feed it
  1272. data. The streamer application will then wait until the stream becomes
  1273. active, and until either the output buffer becomes full, or until it runs
  1274. out of buffer space itself. Then it can unpause the stream knowing that the
  1275. maximum amount of buffering is in use.</p>
  1276.  
  1277. </dd><dt><h5>Related APIs</h5></dt><dd>None</dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_metadatapollchange">AMPlayer_MetaDataPollChange</a><br>
  1278.     (<acronym>SWI &52E0C</acronym>)</h2><dd>Read meta-data state value</dd><dt><h5>On entry</h5></dt><dd>None</dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  1279.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1280.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1281.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1282.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1283.                     should be directed.</td></tr>
  1284.   </table>
  1285.  </td></tr>
  1286.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">opaque unique value, guaranteed to change to a new
  1287.                           unique value when any metadata items change.
  1288.  </td></tr>
  1289.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1290.                           instance handle to direct at, or 0 for
  1291.                           the base</td></tr>
  1292. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1293.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1294.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1295. <p>This SWI is called by streaming applications to discover when meta-data
  1296. provided by the application has been 'passed' by the decoder and is now
  1297. active.</p>
  1298.  
  1299. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_metadatalookup">AMPlayer_MetaDataLookup</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_metadatalookup">AMPlayer_MetaDataLookup</a><br>
  1300.     (<acronym>SWI &52E0C</acronym>)</h2><dd>Read meta-data token value</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1301.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1302.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1303.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1304.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1305.                     should be directed.</td></tr>
  1306.   </table>
  1307.  </td></tr>
  1308.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">pointer to key field to match</td></tr>
  1309.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">pointer to buffer for result (or NULL to read
  1310.                           length)</td></tr>
  1311.  <tr><td valign="top" align="right">R3</td><td valign="top">=</td><td valign="top" align="left">length of buffer, or 0 to read required length
  1312.  </td></tr>
  1313.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1314.                           instance handle to direct at, or 0 for
  1315.                           the base</td></tr>
  1316. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  1317.  <tr><td valign="top" align="right">R0</td><td valign="top" align="left" colspan="2">preserved</td></tr>
  1318.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">buffer, filled with data to length
  1319.                           given</td></tr>
  1320.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">length of buffer required, including
  1321.                           terminator</td></tr>
  1322. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1323.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1324.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1325. <p>This SWI is called by applications to read meta-data passed to the
  1326. AMPlayer module. Every element of meta-data is tagged with a 'key' which
  1327. is used to return its value.</p>
  1328.  
  1329. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_metadatapollchange">AMPlayer_MetaDataPollChange</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_soundsystem">AMPlayer_SoundSystem</a><br>
  1330.     (<acronym>SWI &52E0E</acronym>)</h2><dd>Read sound systems available, or set output sound system</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1331.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1332.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1333.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1334.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1335.                     should be directed.</td></tr>
  1336.   </table>
  1337.  </td></tr>
  1338.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">Operation type :
  1339.   <table summary="Opaque table of values" border="0"><tr><th align="right" valign="bottom">Type</th><th align="left" valign="bottom">Meaning</th></tr>
  1340.    <tr><td valign="top" align="right">-1</td><td valign="top" align="left">Read available sound systems</td></tr>
  1341.    <tr><td valign="top" align="right">0</td><td valign="top" align="left">Select any available system (best possible)</td></tr>
  1342.    <tr><td valign="top" align="right">1</td><td valign="top" align="left">Select 8 bit sound system</td></tr>
  1343.    <tr><td valign="top" align="right">2</td><td valign="top" align="left">Select 16 bit sound system</td></tr>
  1344.    <tr><td valign="top" align="right">3</td><td valign="top" align="left">Select SharedSound</td></tr>
  1345.    <tr><td valign="top" align="right">4</td><td valign="top" align="left">Select 'User' sound system (data read via
  1346.                      <a href="#swi_amplayer_streamreaddata">AMPlayer_StreamReadData</a>)
  1347.                      </td></tr>
  1348.   </table>
  1349.  </td></tr>
  1350.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1351.                           instance handle to direct at, or 0 for
  1352.                           the base</td></tr>
  1353. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  1354.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">Bit mask of avialable sound systems :
  1355.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1356.    <tr><td valign="top" align="right">0</td><td valign="top" align="left" colspan="2">8 bit output available</td></tr>
  1357.    <tr><td valign="top" align="right">1</td><td valign="top" align="left" colspan="2">16 bit output available</td></tr>
  1358.    <tr><td valign="top" align="right">2</td><td valign="top" align="left" colspan="2">SharedSound output available</td></tr>
  1359.    <tr><td valign="top" align="right">3</td><td valign="top" align="left" colspan="2">User output available</td></tr>
  1360.   </table>
  1361.  </td></tr>
  1362.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">Last sound system in use (as on input)
  1363.  </td></tr>
  1364. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1365.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1366.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1367. <p>This SWI is used to determine what sound systems are available on
  1368. the current machine, and to select a different sound system. Its most
  1369. common use is to select the User sound system for streaming output
  1370. data.</p>
  1371.  
  1372. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_streamreaddata">AMPlayer_StreamReadData</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_streamreaddata">AMPlayer_StreamReadData</a><br>
  1373.     (<acronym>SWI &52E0F</acronym>)</h2><dd>Read data from streaming sound system</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1374.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1375.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1376.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1377.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1378.                     should be directed.</td></tr>
  1379.   </table>
  1380.  </td></tr>
  1381.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">Unused</td></tr>
  1382.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">pointer to next byte of data to
  1383.                           read, or 0 for first call</td></tr>
  1384.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1385.                           instance handle to direct at, or 0 for
  1386.                           the base</td></tr>
  1387. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  1388.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">pointer to first byte of data to read, or 0 if
  1389.  none available</td></tr>
  1390.  <tr><td valign="top" align="right">R3</td><td valign="top">=</td><td valign="top" align="left">number of bytes of data available</td></tr>
  1391.  <tr><td valign="top" align="right">R4</td><td valign="top">=</td><td valign="top" align="left">frequency of data</td></tr>
  1392. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1393.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1394.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1395. <p>This SWI is used to take data from the 'user' sound system. Initially,
  1396. users would call with R2 = 0, to determine where to read data from. They
  1397. then take use from this address up to the limit supplied. Subsequently, the
  1398. call this SWI again to inform AMPlayer how much data has been read. AMPlayer
  1399. will only remove data after it has been informed that it has been read.</p>
  1400.  
  1401. <p>Decoding will continue in the background. It may be necessary to delay
  1402. processing if no data is ready. Data can only be generated on callbacks. It
  1403. may, therefore, be necessary to wait for a moment or so for the decode to
  1404. function.</p>
  1405.  
  1406. <p>VU-bars are inactive when use user sound state is in use.</p>
  1407.  
  1408. <p>Callers should note that only complete frames fed in will produce any
  1409. output - not all the input stream may be used.</p>
  1410.  
  1411. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_soundsystem">AMPlayer_SoundSystem</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_instance">AMPlayer_Instance</a><br>
  1412.     (<acronym>SWI &52E10</acronym>)</h2><dd>Manipulate AMPlayer instances</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1413.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1414.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1415.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1416.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1417.                     should be directed.</td></tr>
  1418.   </table>
  1419.  </td></tr>
  1420.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">Reason code :
  1421.   <table summary="Opaque table of values" border="0"><tr><th align="right" valign="bottom">Reason</th><th align="left" valign="bottom">Meaning</th></tr>
  1422.    <tr><td valign="top" align="right">0</td><td valign="top" align="left">
  1423.   <a href="#swi_amplayer_instance-0">Read current instance handle</a>
  1424.    </td></tr>
  1425.    <tr><td valign="top" align="right">1</td><td valign="top" align="left">
  1426.   <a href="#swi_amplayer_instance-1">Create a new instance of the module</a>
  1427.    </td></tr>
  1428.    <tr><td valign="top" align="right">2</td><td valign="top" align="left">
  1429.   <a href="#swi_amplayer_instance-2">Destroy an instance of the module</a>
  1430.    </td></tr>
  1431.    <tr><td valign="top" align="right">3</td><td valign="top" align="left">
  1432.   <a href="#swi_amplayer_instance-3">Read handle of base instance</a>
  1433.    </td></tr>
  1434.    <tr><td valign="top" align="right">4</td><td valign="top" align="left">
  1435.   <a href="#swi_amplayer_instance-4">Enumerate handles of known instances</a>
  1436.    </td></tr>
  1437.   </table>
  1438.  </td></tr>
  1439.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1440.                           instance handle to direct at, or 0 for
  1441.                           the base</td></tr>
  1442. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  1443.  <tr><td valign="top" align="right">R0-7</td><td valign="top">=</td><td valign="top" align="left">dependant on reason code</td></tr>
  1444. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1445.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1446.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1447. <p>This SWI is used control instances of AMPlayer. You should use it in
  1448. preference to directly creating instances of the AMPlayer module yourself.
  1449. Consult the reason code descriptions for more details.</p>
  1450.  
  1451. </dd><dt><h5>Related APIs</h5></dt><dd>None</dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_instance-0">AMPlayer_Instance 0</a><br>
  1452.     (<acronym>SWI &52E10</acronym>)</h2><dd>Read current instance handle</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1453.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1454.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1455.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1456.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1457.                     should be directed.</td></tr>
  1458.   </table>
  1459.  </td></tr>
  1460.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">0 (reason code)</td></tr>
  1461.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1462.                           instance handle to direct at, or 0 for
  1463.                           the base</td></tr>
  1464. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  1465.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">instance handle</td></tr>
  1466. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1467.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1468.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1469. <p>This SWI is used return the instance handle of the current instance of
  1470. AMPlayer. This may be used to discover the handle of the preferred instance
  1471. such that the preferred instance may be changed to allow fading from one
  1472. track to another. It is not expected that this call be used often.</p>
  1473.  
  1474. </dd><dt><h5>Related APIs</h5></dt><dd>None</dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_instance-1">AMPlayer_Instance 1</a><br>
  1475.     (<acronym>SWI &52E10</acronym>)</h2><dd>Create a new instance of the module</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1476.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1477.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1478.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1479.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1480.                     should be directed.</td></tr>
  1481.   </table>
  1482.  </td></tr>
  1483.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">1 (reason code)</td></tr>
  1484.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">pointer to zero terminated suffix for the
  1485.                           instance name. Ideally you should keep this to
  1486.                           < 16 characters.</td></tr>
  1487.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1488.                           instance handle to direct at, or 0 for
  1489.                           the base</td></tr>
  1490. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  1491.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">instance handle of new instance</td></tr>
  1492. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1493.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1494.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1495. <p>This SWI is used create a new instance of the AMPlayer module. This
  1496. instance may be used in exactly the same manner as any other, if SWIs are
  1497. directed at it. Set bit 31 of any SWIs flags to direct the call to the
  1498. instance whose handle is in R8.</p>
  1499.  
  1500. </dd><dt><h5>Related APIs</h5></dt><dd>None</dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_instance-2">AMPlayer_Instance 2</a><br>
  1501.     (<acronym>SWI &52E10</acronym>)</h2><dd>Destroy an instance of the module</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1502.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1503.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1504.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1505.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1506.                     should be directed.</td></tr>
  1507.   </table>
  1508.  </td></tr>
  1509.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">2 (reason code)</td></tr>
  1510.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">instance handle to destroy</td></tr>
  1511.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1512.                           instance handle to direct at, or 0 for
  1513.                           the base</td></tr>
  1514. </table></dd><dt><h5>On exit</h5></dt><dd>None</dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1515.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1516.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1517. <p>This SWI is used destroy an instance of the AMPlayer module. You should
  1518. destroy instances when you have no further use for them, to free up
  1519. resources and processing time.</p>
  1520.  
  1521. </dd><dt><h5>Related APIs</h5></dt><dd>None</dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_instance-3">AMPlayer_Instance 3</a><br>
  1522.     (<acronym>SWI &52E10</acronym>)</h2><dd><p>This SWI call is for internal use only. You must not use it in your
  1523.         own code.</p></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="swi_amplayer_instance-4">AMPlayer_Instance 4</a><br>
  1524.     (<acronym>SWI &52E10</acronym>)</h2><dd>Enumerate handles of known instances</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to SWI" border="0">
  1525.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">flags :
  1526.   <table summary="A bitfield" border="0"><tr><th align="right" valign="bottom">Bit(s)</th><th align="left" valign="bottom">Meaning</th></tr>
  1527.    <tr><td valign="top" align="right">0-30</td><td valign="top" align="left" colspan="2">Reserved, must be 0.</td></tr>
  1528.    <tr><td valign="top" align="right">31</td><td valign="top" align="left" colspan="2">R8 contains the instance handle to which this call
  1529.                     should be directed.</td></tr>
  1530.   </table>
  1531.  </td></tr>
  1532.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">4 (reason code)</td></tr>
  1533.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">last instance handle, or -1 to start enumerating
  1534.  </td></tr>
  1535.  <tr><td valign="top" align="right">R3</td><td valign="top">=</td><td valign="top" align="left">pointer to buffer to write name into</td></tr>
  1536.  <tr><td valign="top" align="right">R4</td><td valign="top">=</td><td valign="top" align="left">length of buffer</td></tr>
  1537.  
  1538.  <tr><td valign="top" align="right">R8</td><td valign="top">=</td><td valign="top" align="left">if bit 31 of R0 set:<br>
  1539.                           instance handle to direct at, or 0 for
  1540.                           the base</td></tr>
  1541. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from SWI" border="0">
  1542.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">instance handle, or -1 if no more</td></tr>
  1543.  <tr><td valign="top" align="right">R4</td><td valign="top">=</td><td valign="top" align="left">length written to buffer, or -ve length if failed
  1544.                           to write</td></tr>
  1545. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are undefined<br>
  1546.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1547.   </dd><dt><h5>Re-entrancy</h5></dt><dd>SWI is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1548. <p>This SWI is used to enumerate the instances currently in use by AMPlayer.
  1549. A 'visualisation' application might use this call to select what source to
  1550. provide a representation of.
  1551. </p>
  1552.  
  1553. </dd><dt><h5>Related APIs</h5></dt><dd>None</dd></dd></dl></dd></dl><hr><dl><dt><h2><a name="section_entry_points">Entry points</a></h2></dt><dd><dl><dd><hr><h2 align="right"><a name="entry_plugin_preprocess">Plugin_PreProcess</a></h2><dd>Pre-process DCT blocks</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to entry-point" border="0">
  1554.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">private word</td></tr>
  1555.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">pointer to 'out 1' buffer</td></tr>
  1556.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">pointer to 'out 2' buffer</td></tr>
  1557.  <tr><td valign="top" align="right">R3</td><td valign="top">=</td><td valign="top" align="left">pointer to 32 frequencies (16.16 format)
  1558.  </td></tr>
  1559. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from entry-point" border="0">
  1560.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">0 if frequencies processed<br>
  1561.                           1 if DCTs done (not recommended)
  1562.  </td></tr>
  1563. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are disabled<br>
  1564.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1565.   </dd><dt><h5>Re-entrancy</h5></dt><dd>Entry-point is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1566. <p>This entry is called prior to 'dct64' which decodes the frequencies into the buffer. Note that there is no way in which to identify whether the buffer is for the left or right channel.</p>
  1567.  
  1568. </dd><dt><h5>Related APIs</h5></dt><dd>None</dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="entry_plugin_postprocess">Plugin_PostProcess</a></h2><dd>Post-process DCT output buffers</dd><dt><h5>On entry</h5></dt><dd><table summary="Conditions on entry to entry-point" border="0">
  1569.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">private word</td></tr>
  1570.  <tr><td valign="top" align="right">R1</td><td valign="top">=</td><td valign="top" align="left">pointer to 'out 1' buffer</td></tr>
  1571.  <tr><td valign="top" align="right">R2</td><td valign="top">=</td><td valign="top" align="left">pointer to 'out 2' buffer</td></tr>
  1572.  <tr><td valign="top" align="right">R3</td><td valign="top">=</td><td valign="top" align="left">pointer to samples buffer</td></tr>
  1573. </table></dd><dt><h5>On exit</h5></dt><dd><table summary="Conditions on exit from entry-point" border="0">
  1574.  <tr><td valign="top" align="right">R0</td><td valign="top">=</td><td valign="top" align="left">0 if buffer processed
  1575.  </td></tr>
  1576. </table></dd><dt><h5>Interrupts</h5></dt><dd>Interrupts are disabled<br>
  1577.       Fast interrupts are enabled</dd><dt><h5>Processor mode</h5></dt><dd>Processor is in SVC mode
  1578.   </dd><dt><h5>Re-entrancy</h5></dt><dd>Entry-point is not re-entrant</dd><dt><h5>Use</h5></dt><dd>
  1579. <p>This entry is called after the 'dct64' which decodes the frequencies into
  1580. the buffer. Note that there is no way in which to identify whether the
  1581. buffer is for the left or right channel. </p>
  1582.  
  1583. </dd><dt><h5>Related APIs</h5></dt><dd>None</dd></dd></dl></dd></dl><hr><dl><dt><h2><a name="section_commands">*Commands</a></h2></dt><dd><dl><dd><hr><h2 align="right"><a name="command_aminfo">*AMInfo</a></h2><dd>Read information on playback, plugins or file</dd><dt><h5>Syntax</h5></dt><dd><code>*AMInfo
  1584.  [-plugins]
  1585.  [-file <i><filename></i>]
  1586. </code></dd><dt><h5>Parameters</h5></dt><dd><table summary="Command parameters" border="0"><tr><td valign="top"><code>
  1587.           -plugins </code></td><td valign="top">-</td><td valign="top">
  1588.  Display information about the plugins currently active.
  1589. </td></tr><tr><td valign="top"><code>
  1590.           -file <i><filename></i></code></td><td valign="top">-</td><td valign="top">
  1591.  Display information about a file, rather than about the current playback
  1592.  state.
  1593. </td></tr></table></dd><dt><h5>Use</h5></dt><dd>
  1594. <p>This command is used to display information about the current playback
  1595. state, or the state of the plugins.</p>
  1596. </dd><dt><h5>Example</h5></dt><dd>
  1597. <code>*AMInfo -file Corrs,The.01ForgivenNotForgotten.01ErinShore(TraditionalIntro)</code>
  1598. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_info">AMPlayer_Info</a>, <a href="#swi_amplayer_fileinfo">AMPlayer_FileInfo</a>, <a href="#swi_amplayer_plugin">AMPlayer_Plugin</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="command_amlocate">*AMLocate</a></h2><dd>Skip to a position in the current file</dd><dt><h5>Syntax</h5></dt><dd><code>*AMLocate
  1599.  [+ | -]
  1600.  <i><hours></i>:<i><minutes></i>:<i><seconds></i>
  1601. </code><br><code>*AMLocate
  1602.  <i><minutes></i>:<i><seconds></i>
  1603. </code></dd><dt><h5>Parameters</h5></dt><dd><table summary="Command parameters" border="0"><tr><td valign="top"><code><i><hours></i></code></td><td valign="top">-</td><td valign="top">Number of hours to search for</td></tr><tr><td valign="top"><code><i><minutes></i></code></td><td valign="top">-</td><td valign="top">Number of minutes to search for</td></tr><tr><td valign="top"><code><i><seconds></i></code></td><td valign="top">-</td><td valign="top">Number of seconds to search for</td></tr></table></dd><dt><h5>Use</h5></dt><dd>
  1604. <p>This command is used to jump to a point in the playback of the file. Use
  1605. + and - to indicate a location relative to the current playback position.
  1606. </p>
  1607. </dd><dt><h5>Example</h5></dt><dd>
  1608. <code>*AMLocate 7:23</code>
  1609. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_locate">AMPlayer_Locate</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="command_ampause">*AMPause</a></h2><dd>Pause, or resume, playback</dd><dt><h5>Syntax</h5></dt><dd><code>*AMPause
  1610.  [-off]
  1611. </code></dd><dt><h5>Parameters</h5></dt><dd><table summary="Command parameters" border="0"><tr><td valign="top"><code>
  1612.           -off </code></td><td valign="top">-</td><td valign="top">resume playback, instead of pausing</td></tr></table></dd><dt><h5>Use</h5></dt><dd>
  1613. <p>This command is used to pause, or resume playback.</p>
  1614. </dd><dt><h5>Example</h5></dt><dd>
  1615. <code>*AMPause</code>
  1616. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_pause">AMPlayer_Pause</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="command_amplay">*AMPlay</a></h2><dd>Play a new file</dd><dt><h5>Syntax</h5></dt><dd><code>*AMPlay
  1617.  [-next]
  1618.  [-queue]
  1619.  [-cue]
  1620.  [-transient]
  1621.  <i><filename></i>
  1622. </code></dd><dt><h5>Parameters</h5></dt><dd><table summary="Command parameters" border="0"><tr><td valign="top"><code>
  1623.           -next </code></td><td valign="top">-</td><td valign="top">Start playback of queued file immediately</td></tr><tr><td valign="top"><code>
  1624.           -queue </code></td><td valign="top">-</td><td valign="top">Queue this file, rather than playing it
  1625. immediately</td></tr><tr><td valign="top"><code>
  1626.           -cue </code></td><td valign="top">-</td><td valign="top">Start decoding this track, but leave the player
  1627. paused</td></tr><tr><td valign="top"><code>
  1628.           -transient </code></td><td valign="top">-</td><td valign="top">Start decoding this track in a new instance
  1629. which will terminate when playback completes.</td></tr></table></dd><dt><h5>Use</h5></dt><dd>
  1630. <p>This command is used to play a new file.</p>
  1631. </dd><dt><h5>Example</h5></dt><dd>
  1632. <code>*AMPlay -queue ADFS::4.$.Music.Artists.Dido.NoAngel.06Thankyou</code>
  1633. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_play">AMPlayer_Play</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="command_amstop">*AMStop</a></h2><dd>Stops playback</dd><dt><h5>Syntax</h5></dt><dd><code>*AMStop</code></dd><dt><h5>Parameters</h5></dt><dd>None</dd><dt><h5>Use</h5></dt><dd>
  1634. <p>This command is used to stop playback.</p>
  1635. </dd><dt><h5>Example</h5></dt><dd>
  1636. <code>*AMStop</code>
  1637. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_stop">AMPlayer_Stop</a></dd></dd></dl></dd><dd><dl><dd><hr><h2 align="right"><a name="command_amvolume">*AMVolume</a></h2><dd>AMVolume</dd><dt><h5>Syntax</h5></dt><dd><code>*AMVolume
  1638.  [+ | -]
  1639.  <i><volume></i>
  1640. </code></dd><dt><h5>Parameters</h5></dt><dd><table summary="Command parameters" border="0"><tr><td valign="top"><code><i><volume></i></code></td><td valign="top">-</td><td valign="top">volume level (0-127)</td></tr></table></dd><dt><h5>Use</h5></dt><dd>
  1641. <p>This command is set the playback volume. Initially, 113 is selected.</p>
  1642. </dd><dt><h5>Example</h5></dt><dd>
  1643. <code>*AMVolume 113</code>
  1644. </dd><dt><h5>Related SWIs</h5></dt><dd><a href="#swi_amplayer_control-0">AMPlayer_Control 0</a></dd><dt><h5>Related system variables</h5></dt><dd><a href="#sysvar_amplayer_volume">AMPlayer$Volume</a></dd></dd></dl></dd></dl><hr></body>
  1645. </html>
  1646.